ai-qakit 1.0.0

package/templates/.claude/commands/devkit/frontend/create-table.md

@@ -0,0 +1,1035 @@
+---
+description: Generate data table component with sorting, filtering, and pagination
+argument-hint: [table-description]
+allowed-tools: Read, Grep, Write, Edit, AskUserQuestion
+---
+
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.
+
+---
+
+**Report Protocol**: Follow ./.claude/CLAUDE.md "Sub-Agent Report Generation" protocol before spawning subagents.
+
+# Create Table
+
+Generate data table for: $ARGUMENTS
+
+## ⚠️ Plan Before Executing
+
+**Always create a structured plan and get user approval before making changes.**
+
+1. Analyze the request and show table design
+2. Display the columns with data types and features
+3. Show all files that will be created
+4. Ask for confirmation before writing files
+5. Never create tables without user approval
+
+## Important: Ask for Clarification
+
+**If anything is unclear, DO NOT GUESS. Ask the user:**
+
+- "What columns should this table display?"
+- "Which columns should be sortable?"
+- "Should this include search/filter functionality?"
+- "Is pagination needed? Server-side or client-side?"
+- "Should rows be selectable? Single or multi-select?"
+- "Are there any row actions (edit, delete, view)?"
+- "Should columns be resizable or reorderable?"
+- "Do any columns need custom cell rendering?"
+
+Use AskUserQuestion tool when you need more context before proceeding.
+
+## Step 1: Reference Project Profile
+
+Read @.claude/CLAUDE.md to understand:
+- Table library (TanStack Table, AG Grid, custom)
+- UI components (shadcn/ui, MUI, custom)
+- Styling approach
+- Data fetching patterns
+- Pagination approach (server-side, client-side)
+
+If `.claude/CLAUDE.md` doesn't exist, run `/init` first.
+
+## Step 2: Parse Request
+
+Analyze "$ARGUMENTS" to determine:
+- Table name (UsersTable, ProductsTable)
+- Data type/resource
+- Column requirements
+- Features needed (sorting, filtering, pagination)
+- Row actions
+
+**Common table types:**
+- `List` - Simple display with basic actions
+- `Data Grid` - Full-featured with editing
+- `Selection` - Multi-select with bulk actions
+- `Infinite` - Virtual scrolling for large datasets
+- `Nested` - Expandable rows with child data
+
+## Step 3: Review Existing Tables
+
+Find and analyze existing tables to detect:
+- Table component patterns
+- Column definition approach
+- Sorting implementation
+- Filter patterns
+- Pagination component
+- Row action menus
+- Loading/empty states
+
+## Step 4: Define Column Types
+
+```typescript
+// types/table.ts
+export interface ColumnDef<T> {
+  id: string
+  header: string
+  accessorKey?: keyof T
+  cell?: (info: { row: T }) => React.ReactNode
+  sortable?: boolean
+  filterable?: boolean
+  width?: number | string
+}
+
+export interface TableState {
+  sorting: SortingState
+  pagination: PaginationState
+  filters: FilterState
+  selection: SelectionState
+}
+
+export interface PaginationState {
+  pageIndex: number
+  pageSize: number
+  total: number
+}
+
+export interface SortingState {
+  column: string | null
+  direction: 'asc' | 'desc'
+}
+```
+
+## Step 5: Generate Table Component
+
+### TanStack Table + shadcn/ui
+
+```typescript
+// components/tables/UsersTable.tsx
+'use client'
+
+import { useState } from 'react'
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  flexRender,
+  type ColumnDef,
+  type SortingState,
+  type ColumnFiltersState,
+  type VisibilityState,
+} from '@tanstack/react-table'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu'
+import { Checkbox } from '@/components/ui/checkbox'
+import {
+  ArrowUpDown,
+  ChevronDown,
+  MoreHorizontal,
+  Pencil,
+  Trash2,
+  Eye,
+} from 'lucide-react'
+import type { User } from '@/types/user'
+
+interface UsersTableProps {
+  data: User[]
+  isLoading?: boolean
+  onEdit?: (user: User) => void
+  onDelete?: (user: User) => void
+  onView?: (user: User) => void
+}
+
+const columns: ColumnDef<User>[] = [
+  {
+    id: 'select',
+    header: ({ table }) => (
+      <Checkbox
+        checked={table.getIsAllPageRowsSelected()}
+        onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
+        aria-label="Select all"
+      />
+    ),
+    cell: ({ row }) => (
+      <Checkbox
+        checked={row.getIsSelected()}
+        onCheckedChange={(value) => row.toggleSelected(!!value)}
+        aria-label="Select row"
+      />
+    ),
+    enableSorting: false,
+    enableHiding: false,
+  },
+  {
+    accessorKey: 'name',
+    header: ({ column }) => (
+      <Button
+        variant="ghost"
+        onClick={() => column.toggleSorting(column.getIsSorted() === 'asc')}
+      >
+        Name
+        <ArrowUpDown className="ml-2 h-4 w-4" />
+      </Button>
+    ),
+    cell: ({ row }) => (
+      <div className="flex items-center gap-2">
+        <img
+          src={row.original.avatar}
+          alt={row.getValue('name')}
+          className="h-8 w-8 rounded-full"
+        />
+        <span className="font-medium">{row.getValue('name')}</span>
+      </div>
+    ),
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => (
+      <Button
+        variant="ghost"
+        onClick={() => column.toggleSorting(column.getIsSorted() === 'asc')}
+      >
+        Email
+        <ArrowUpDown className="ml-2 h-4 w-4" />
+      </Button>
+    ),
+  },
+  {
+    accessorKey: 'role',
+    header: 'Role',
+    cell: ({ row }) => {
+      const role = row.getValue('role') as string
+      return (
+        <span
+          className={cn(
+            'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium',
+            role === 'admin'
+              ? 'bg-purple-100 text-purple-800'
+              : 'bg-gray-100 text-gray-800'
+          )}
+        >
+          {role}
+        </span>
+      )
+    },
+    filterFn: (row, id, value) => value.includes(row.getValue(id)),
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: ({ row }) => {
+      const status = row.getValue('status') as string
+      return (
+        <span
+          className={cn(
+            'inline-flex items-center gap-1 rounded-full px-2.5 py-0.5 text-xs font-medium',
+            status === 'active'
+              ? 'bg-green-100 text-green-800'
+              : 'bg-red-100 text-red-800'
+          )}
+        >
+          <span
+            className={cn(
+              'h-1.5 w-1.5 rounded-full',
+              status === 'active' ? 'bg-green-500' : 'bg-red-500'
+            )}
+          />
+          {status}
+        </span>
+      )
+    },
+  },
+  {
+    accessorKey: 'createdAt',
+    header: 'Created',
+    cell: ({ row }) => {
+      const date = new Date(row.getValue('createdAt'))
+      return <span>{date.toLocaleDateString()}</span>
+    },
+  },
+  {
+    id: 'actions',
+    enableHiding: false,
+    cell: ({ row, table }) => {
+      const user = row.original
+      const { onEdit, onDelete, onView } = table.options.meta as UsersTableProps
+
+      return (
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="ghost" className="h-8 w-8 p-0">
+              <span className="sr-only">Open menu</span>
+              <MoreHorizontal className="h-4 w-4" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuLabel>Actions</DropdownMenuLabel>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem onClick={() => onView?.(user)}>
+              <Eye className="mr-2 h-4 w-4" />
+              View
+            </DropdownMenuItem>
+            <DropdownMenuItem onClick={() => onEdit?.(user)}>
+              <Pencil className="mr-2 h-4 w-4" />
+              Edit
+            </DropdownMenuItem>
+            <DropdownMenuItem
+              onClick={() => onDelete?.(user)}
+              className="text-red-600"
+            >
+              <Trash2 className="mr-2 h-4 w-4" />
+              Delete
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      )
+    },
+  },
+]
+
+export function UsersTable({
+  data,
+  isLoading,
+  onEdit,
+  onDelete,
+  onView,
+}: UsersTableProps) {
+  const [sorting, setSorting] = useState<SortingState>([])
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
+  const [rowSelection, setRowSelection] = useState({})
+
+  const table = useReactTable({
+    data,
+    columns,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    onSortingChange: setSorting,
+    onColumnFiltersChange: setColumnFilters,
+    onColumnVisibilityChange: setColumnVisibility,
+    onRowSelectionChange: setRowSelection,
+    state: {
+      sorting,
+      columnFilters,
+      columnVisibility,
+      rowSelection,
+    },
+    meta: { onEdit, onDelete, onView },
+  })
+
+  return (
+    <div className="space-y-4">
+      {/* Toolbar */}
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <Input
+            placeholder="Filter by name..."
+            value={(table.getColumn('name')?.getFilterValue() as string) ?? ''}
+            onChange={(e) =>
+              table.getColumn('name')?.setFilterValue(e.target.value)
+            }
+            className="max-w-sm"
+          />
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button variant="outline">
+                Columns <ChevronDown className="ml-2 h-4 w-4" />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              {table
+                .getAllColumns()
+                .filter((column) => column.getCanHide())
+                .map((column) => (
+                  <DropdownMenuItem
+                    key={column.id}
+                    className="capitalize"
+                    onClick={() => column.toggleVisibility(!column.getIsVisible())}
+                  >
+                    <Checkbox
+                      checked={column.getIsVisible()}
+                      className="mr-2"
+                    />
+                    {column.id}
+                  </DropdownMenuItem>
+                ))}
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </div>
+
+        {Object.keys(rowSelection).length > 0 && (
+          <div className="flex items-center gap-2">
+            <span className="text-sm text-muted-foreground">
+              {Object.keys(rowSelection).length} selected
+            </span>
+            <Button variant="destructive" size="sm">
+              Delete Selected
+            </Button>
+          </div>
+        )}
+      </div>
+
+      {/* Table */}
+      <div className="rounded-md border">
+        <Table>
+          <TableHeader>
+            {table.getHeaderGroups().map((headerGroup) => (
+              <TableRow key={headerGroup.id}>
+                {headerGroup.headers.map((header) => (
+                  <TableHead key={header.id}>
+                    {header.isPlaceholder
+                      ? null
+                      : flexRender(
+                          header.column.columnDef.header,
+                          header.getContext()
+                        )}
+                  </TableHead>
+                ))}
+              </TableRow>
+            ))}
+          </TableHeader>
+          <TableBody>
+            {isLoading ? (
+              <TableRow>
+                <TableCell
+                  colSpan={columns.length}
+                  className="h-24 text-center"
+                >
+                  <div className="flex items-center justify-center">
+                    <Loader2 className="h-6 w-6 animate-spin" />
+                  </div>
+                </TableCell>
+              </TableRow>
+            ) : table.getRowModel().rows?.length ? (
+              table.getRowModel().rows.map((row) => (
+                <TableRow
+                  key={row.id}
+                  data-state={row.getIsSelected() && 'selected'}
+                >
+                  {row.getVisibleCells().map((cell) => (
+                    <TableCell key={cell.id}>
+                      {flexRender(
+                        cell.column.columnDef.cell,
+                        cell.getContext()
+                      )}
+                    </TableCell>
+                  ))}
+                </TableRow>
+              ))
+            ) : (
+              <TableRow>
+                <TableCell
+                  colSpan={columns.length}
+                  className="h-24 text-center"
+                >
+                  No results.
+                </TableCell>
+              </TableRow>
+            )}
+          </TableBody>
+        </Table>
+      </div>
+
+      {/* Pagination */}
+      <div className="flex items-center justify-between px-2">
+        <div className="text-sm text-muted-foreground">
+          {table.getFilteredSelectedRowModel().rows.length} of{' '}
+          {table.getFilteredRowModel().rows.length} row(s) selected.
+        </div>
+        <div className="flex items-center space-x-2">
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => table.previousPage()}
+            disabled={!table.getCanPreviousPage()}
+          >
+            Previous
+          </Button>
+          <div className="text-sm">
+            Page {table.getState().pagination.pageIndex + 1} of{' '}
+            {table.getPageCount()}
+          </div>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => table.nextPage()}
+            disabled={!table.getCanNextPage()}
+          >
+            Next
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+### Server-Side Pagination
+
+```typescript
+// components/tables/UsersTableServer.tsx
+'use client'
+
+import { useSearchParams, useRouter, usePathname } from 'next/navigation'
+import { useUsers } from '@/hooks/users'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+import { useDebouncedCallback } from 'use-debounce'
+
+export function UsersTableServer() {
+  const searchParams = useSearchParams()
+  const pathname = usePathname()
+  const router = useRouter()
+
+  const page = Number(searchParams.get('page')) || 1
+  const limit = Number(searchParams.get('limit')) || 10
+  const search = searchParams.get('search') || ''
+  const sortBy = searchParams.get('sortBy') || 'createdAt'
+  const sortOrder = (searchParams.get('sortOrder') as 'asc' | 'desc') || 'desc'
+
+  const { data, isLoading } = useUsers({
+    page,
+    limit,
+    search,
+    sortBy,
+    sortOrder,
+  })
+
+  const updateParams = (updates: Record<string, string | number>) => {
+    const params = new URLSearchParams(searchParams)
+    Object.entries(updates).forEach(([key, value]) => {
+      if (value) {
+        params.set(key, String(value))
+      } else {
+        params.delete(key)
+      }
+    })
+    router.push(`${pathname}?${params.toString()}`)
+  }
+
+  const handleSearch = useDebouncedCallback((term: string) => {
+    updateParams({ search: term, page: 1 })
+  }, 300)
+
+  const handleSort = (column: string) => {
+    const newOrder =
+      sortBy === column && sortOrder === 'asc' ? 'desc' : 'asc'
+    updateParams({ sortBy: column, sortOrder: newOrder })
+  }
+
+  const handlePageChange = (newPage: number) => {
+    updateParams({ page: newPage })
+  }
+
+  const handleLimitChange = (newLimit: string) => {
+    updateParams({ limit: parseInt(newLimit), page: 1 })
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* Search */}
+      <div className="flex items-center gap-4">
+        <Input
+          placeholder="Search users..."
+          defaultValue={search}
+          onChange={(e) => handleSearch(e.target.value)}
+          className="max-w-sm"
+        />
+        <Select value={String(limit)} onValueChange={handleLimitChange}>
+          <SelectTrigger className="w-[180px]">
+            <SelectValue placeholder="Rows per page" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="10">10 per page</SelectItem>
+            <SelectItem value="25">25 per page</SelectItem>
+            <SelectItem value="50">50 per page</SelectItem>
+            <SelectItem value="100">100 per page</SelectItem>
+          </SelectContent>
+        </Select>
+      </div>
+
+      {/* Table */}
+      <div className="rounded-md border">
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead
+                className="cursor-pointer"
+                onClick={() => handleSort('name')}
+              >
+                Name {sortBy === 'name' && (sortOrder === 'asc' ? '↑' : '↓')}
+              </TableHead>
+              <TableHead
+                className="cursor-pointer"
+                onClick={() => handleSort('email')}
+              >
+                Email {sortBy === 'email' && (sortOrder === 'asc' ? '↑' : '↓')}
+              </TableHead>
+              <TableHead>Role</TableHead>
+              <TableHead
+                className="cursor-pointer"
+                onClick={() => handleSort('createdAt')}
+              >
+                Created{' '}
+                {sortBy === 'createdAt' && (sortOrder === 'asc' ? '↑' : '↓')}
+              </TableHead>
+            </TableRow>
+          </TableHeader>
+          <TableBody>
+            {isLoading ? (
+              <TableRow>
+                <TableCell colSpan={4} className="h-24 text-center">
+                  Loading...
+                </TableCell>
+              </TableRow>
+            ) : data?.data.length ? (
+              data.data.map((user) => (
+                <TableRow key={user.id}>
+                  <TableCell>{user.name}</TableCell>
+                  <TableCell>{user.email}</TableCell>
+                  <TableCell>{user.role}</TableCell>
+                  <TableCell>
+                    {new Date(user.createdAt).toLocaleDateString()}
+                  </TableCell>
+                </TableRow>
+              ))
+            ) : (
+              <TableRow>
+                <TableCell colSpan={4} className="h-24 text-center">
+                  No results.
+                </TableCell>
+              </TableRow>
+            )}
+          </TableBody>
+        </Table>
+      </div>
+
+      {/* Pagination */}
+      <div className="flex items-center justify-between">
+        <div className="text-sm text-muted-foreground">
+          Showing {(page - 1) * limit + 1} to{' '}
+          {Math.min(page * limit, data?.meta.total || 0)} of{' '}
+          {data?.meta.total || 0} results
+        </div>
+        <div className="flex items-center gap-2">
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => handlePageChange(page - 1)}
+            disabled={page === 1}
+          >
+            Previous
+          </Button>
+          <div className="text-sm">
+            Page {page} of {data?.meta.totalPages || 1}
+          </div>
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => handlePageChange(page + 1)}
+            disabled={page >= (data?.meta.totalPages || 1)}
+          >
+            Next
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}
+```
+
+### Reusable DataTable Component
+
+```typescript
+// components/tables/DataTable.tsx
+'use client'
+
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  flexRender,
+  type ColumnDef,
+  type TableOptions,
+} from '@tanstack/react-table'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table'
+import { DataTablePagination } from './DataTablePagination'
+import { DataTableToolbar } from './DataTableToolbar'
+
+interface DataTableProps<TData, TValue> {
+  columns: ColumnDef<TData, TValue>[]
+  data: TData[]
+  searchKey?: string
+  searchPlaceholder?: string
+  isLoading?: boolean
+  filterOptions?: {
+    column: string
+    title: string
+    options: { label: string; value: string }[]
+  }[]
+}
+
+export function DataTable<TData, TValue>({
+  columns,
+  data,
+  searchKey,
+  searchPlaceholder = 'Search...',
+  isLoading,
+  filterOptions,
+}: DataTableProps<TData, TValue>) {
+  const [sorting, setSorting] = useState<SortingState>([])
+  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([])
+  const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({})
+  const [rowSelection, setRowSelection] = useState({})
+
+  const table = useReactTable({
+    data,
+    columns,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getPaginationRowModel: getPaginationRowModel(),
+    onSortingChange: setSorting,
+    onColumnFiltersChange: setColumnFilters,
+    onColumnVisibilityChange: setColumnVisibility,
+    onRowSelectionChange: setRowSelection,
+    state: {
+      sorting,
+      columnFilters,
+      columnVisibility,
+      rowSelection,
+    },
+  })
+
+  return (
+    <div className="space-y-4">
+      <DataTableToolbar
+        table={table}
+        searchKey={searchKey}
+        searchPlaceholder={searchPlaceholder}
+        filterOptions={filterOptions}
+      />
+
+      <div className="rounded-md border">
+        <Table>
+          <TableHeader>
+            {table.getHeaderGroups().map((headerGroup) => (
+              <TableRow key={headerGroup.id}>
+                {headerGroup.headers.map((header) => (
+                  <TableHead key={header.id}>
+                    {header.isPlaceholder
+                      ? null
+                      : flexRender(
+                          header.column.columnDef.header,
+                          header.getContext()
+                        )}
+                  </TableHead>
+                ))}
+              </TableRow>
+            ))}
+          </TableHeader>
+          <TableBody>
+            {isLoading ? (
+              <TableRow>
+                <TableCell
+                  colSpan={columns.length}
+                  className="h-24 text-center"
+                >
+                  Loading...
+                </TableCell>
+              </TableRow>
+            ) : table.getRowModel().rows?.length ? (
+              table.getRowModel().rows.map((row) => (
+                <TableRow
+                  key={row.id}
+                  data-state={row.getIsSelected() && 'selected'}
+                >
+                  {row.getVisibleCells().map((cell) => (
+                    <TableCell key={cell.id}>
+                      {flexRender(
+                        cell.column.columnDef.cell,
+                        cell.getContext()
+                      )}
+                    </TableCell>
+                  ))}
+                </TableRow>
+              ))
+            ) : (
+              <TableRow>
+                <TableCell
+                  colSpan={columns.length}
+                  className="h-24 text-center"
+                >
+                  No results.
+                </TableCell>
+              </TableRow>
+            )}
+          </TableBody>
+        </Table>
+      </div>
+
+      <DataTablePagination table={table} />
+    </div>
+  )
+}
+```
+
+## Step 6: Generate Tests
+
+```typescript
+// components/tables/UsersTable.test.tsx
+import { render, screen, within } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { UsersTable } from './UsersTable'
+
+const mockUsers = [
+  {
+    id: '1',
+    name: 'John Doe',
+    email: 'john@example.com',
+    role: 'admin',
+    status: 'active',
+    createdAt: '2024-01-01',
+    avatar: 'https://example.com/avatar.jpg',
+  },
+  {
+    id: '2',
+    name: 'Jane Smith',
+    email: 'jane@example.com',
+    role: 'user',
+    status: 'inactive',
+    createdAt: '2024-01-02',
+    avatar: 'https://example.com/avatar2.jpg',
+  },
+]
+
+describe('UsersTable', () => {
+  it('renders table with data', () => {
+    render(<UsersTable data={mockUsers} />)
+
+    expect(screen.getByText('John Doe')).toBeInTheDocument()
+    expect(screen.getByText('jane@example.com')).toBeInTheDocument()
+  })
+
+  it('shows loading state', () => {
+    render(<UsersTable data={[]} isLoading />)
+
+    expect(screen.getByRole('status')).toBeInTheDocument()
+  })
+
+  it('shows empty state when no data', () => {
+    render(<UsersTable data={[]} />)
+
+    expect(screen.getByText(/no results/i)).toBeInTheDocument()
+  })
+
+  it('filters table by name', async () => {
+    const user = userEvent.setup()
+    render(<UsersTable data={mockUsers} />)
+
+    const searchInput = screen.getByPlaceholderText(/filter by name/i)
+    await user.type(searchInput, 'John')
+
+    expect(screen.getByText('John Doe')).toBeInTheDocument()
+    expect(screen.queryByText('Jane Smith')).not.toBeInTheDocument()
+  })
+
+  it('sorts table by column', async () => {
+    const user = userEvent.setup()
+    render(<UsersTable data={mockUsers} />)
+
+    const nameHeader = screen.getByRole('button', { name: /name/i })
+    await user.click(nameHeader)
+
+    const rows = screen.getAllByRole('row')
+    expect(within(rows[1]).getByText('Jane Smith')).toBeInTheDocument()
+  })
+
+  it('selects rows', async () => {
+    const user = userEvent.setup()
+    render(<UsersTable data={mockUsers} />)
+
+    const checkboxes = screen.getAllByRole('checkbox')
+    await user.click(checkboxes[1]) // First data row
+
+    expect(screen.getByText(/1 selected/i)).toBeInTheDocument()
+  })
+
+  it('calls action handlers', async () => {
+    const user = userEvent.setup()
+    const onEdit = vi.fn()
+    const onDelete = vi.fn()
+
+    render(<UsersTable data={mockUsers} onEdit={onEdit} onDelete={onDelete} />)
+
+    const actionButtons = screen.getAllByRole('button', { name: /open menu/i })
+    await user.click(actionButtons[0])
+
+    await user.click(screen.getByRole('menuitem', { name: /edit/i }))
+    expect(onEdit).toHaveBeenCalledWith(mockUsers[0])
+  })
+
+  it('paginates data', async () => {
+    const user = userEvent.setup()
+    const manyUsers = Array.from({ length: 25 }, (_, i) => ({
+      ...mockUsers[0],
+      id: String(i),
+      name: `User ${i}`,
+    }))
+
+    render(<UsersTable data={manyUsers} />)
+
+    expect(screen.getByText('Page 1 of 3')).toBeInTheDocument()
+
+    await user.click(screen.getByRole('button', { name: /next/i }))
+    expect(screen.getByText('Page 2 of 3')).toBeInTheDocument()
+  })
+})
+```
+
+## Step 7: Show Generated Files
+
+Display:
+1. All file paths to create
+2. Full content for each file
+3. Table structure diagram:
+
+```
+┌─────────────────────────────────────┐
+│ Table: UsersTable                   │
+├─────────────────────────────────────┤
+│ Library: TanStack Table             │
+│ UI: shadcn/ui                       │
+│ Pagination: Client-side             │
+├─────────────────────────────────────┤
+│ Columns:                            │
+│   - select (checkbox)               │
+│   - name (sortable, filterable)     │
+│   - email (sortable)                │
+│   - role (filterable)               │
+│   - status (badge)                  │
+│   - createdAt (date)                │
+│   - actions (menu)                  │
+├─────────────────────────────────────┤
+│ Features:                           │
+│   ✓ Sorting                         │
+│   ✓ Filtering                       │
+│   ✓ Pagination                      │
+│   ✓ Row selection                   │
+│   ✓ Column visibility               │
+│   ✓ Row actions                     │
+├─────────────────────────────────────┤
+│ Files:                              │
+│   - components/tables/UsersTable.tsx│
+│   - components/tables/UsersTable.test.tsx │
+└─────────────────────────────────────┘
+```
+
+## Step 8: Usage Example
+
+```typescript
+import { UsersTable } from '@/components/tables/UsersTable'
+import { useUsers, useDeleteUser } from '@/hooks/users'
+import { toast } from 'sonner'
+
+function UsersPage() {
+  const { data, isLoading } = useUsers()
+  const deleteUser = useDeleteUser()
+
+  const handleEdit = (user: User) => {
+    router.push(`/users/${user.id}/edit`)
+  }
+
+  const handleDelete = async (user: User) => {
+    if (confirm(`Delete ${user.name}?`)) {
+      try {
+        await deleteUser.mutateAsync(user.id)
+        toast.success('User deleted')
+      } catch (error) {
+        toast.error('Failed to delete user')
+      }
+    }
+  }
+
+  const handleView = (user: User) => {
+    router.push(`/users/${user.id}`)
+  }
+
+  return (
+    <div className="container mx-auto py-10">
+      <h1 className="text-2xl font-bold mb-6">Users</h1>
+      <UsersTable
+        data={data?.data || []}
+        isLoading={isLoading}
+        onEdit={handleEdit}
+        onDelete={handleDelete}
+        onView={handleView}
+      />
+    </div>
+  )
+}
+```
+
+## Step 9: Next Steps
+
+Suggest related actions:
+- Create API integration: `/create-api-integration users`
+- Create form for editing: `/create-form UserForm`
+- Add Storybook stories: `/create-storybook UsersTable`
+- Create detail page: `/create-page user detail with tabs`
+
+Generate table now for: $ARGUMENTS