1 files changed, 159 insertions, 0 deletions
diff --git a/components/client-table/README.md b/components/client-table/README.md
new file mode 100644
index 00000000..053175d4
--- /dev/null
+++ b/components/client-table/README.md
@@ -0,0 +1,159 @@
+# Client Table Components
+
+A set of reusable, virtualized table components for client-side data rendering, built on top of `@tanstack/react-table` and `@tanstack/react-virtual`.
+
+## Features
+
+- **Virtualization**: Efficiently renders large datasets (50,000+ rows) by only rendering visible rows.
+- **Sorting**: Built-in column sorting (Ascending/Descending).
+- **Filtering**:
+  - Global search (all columns).
+  - Column-specific filters: Text (default), Select, Boolean.
+- **Pagination**: Supports both client-side and server-side (manual) pagination.
+- **Column Management**:
+  - **Reordering**: Drag and drop columns to change order.
+  - **Hiding**: Right-click header to hide columns.
+  - **Pinning**: Right-click header to pin columns (Left/Right).
+- **Excel Export**: Export current table view or custom datasets to `.xlsx`.
+- **Excel Import**: Utility to parse Excel files into JSON objects.
+- **Template Generation**: Create Excel templates for users to fill out and import.
+
+## Installation / Usage
+
+The components are located in `@/components/client-table`.
+
+### 1. Basic Usage
+
+```tsx
+import { ClientVirtualTable, ClientTableColumnDef } from "@/components/client-table"
+
+// 1. Define Data Type
+interface User {
+  id: string
+  name: string
+  role: string
+  active: boolean
+}
+
+// 2. Define Columns
+const columns: ClientTableColumnDef<User>[] = [
+  {
+    accessorKey: "name",
+    header: "Name",
+    // Default filter is text
+  },
+  {
+    accessorKey: "role",
+    header: "Role",
+    meta: {
+      filterType: "select",
+      filterOptions: [
+        { label: "Admin", value: "admin" },
+        { label: "User", value: "user" },
+      ]
+    }
+  },
+  {
+    accessorKey: "active",
+    header: "Active",
+    meta: {
+      filterType: "boolean"
+    }
+  }
+]
+
+// 3. Render Component
+export default function UserTable({ data }: { data: User[] }) {
+  return (
+    <ClientVirtualTable
+      data={data}
+      columns={columns}
+      height="600px" // Required for virtualization
+      enableExport={true} // Shows export button
+      enablePagination={true} // Shows pagination footer
+    />
+  )
+}
+```
+
+### 2. Server-Side Pagination
+
+For very large datasets where you don't want to fetch everything at once.
+
+```tsx
+<ClientVirtualTable
+  data={currentData} // Only the current page data
+  columns={columns}
+  manualPagination={true}
+  pageCount={totalPages}
+  rowCount={totalRows}
+  pagination={{ pageIndex, pageSize }}
+  onPaginationChange={setPaginationState}
+  enablePagination={true}
+/>
+```
+
+### 3. Excel Utilities
+
+#### Exporting Data
+
+Automatic export is available via the `enableExport` prop. For custom export logic:
+
+```tsx
+import { exportToExcel } from "@/components/client-table"
+
+await exportToExcel(data, columns, "my-data.xlsx")
+```
+
+#### Creating Import Templates
+
+Generate a blank Excel file with headers for users to fill in.
+
+```tsx
+import { createExcelTemplate } from "@/components/client-table"
+
+await createExcelTemplate({
+  columns,
+  filename: "user-import-template.xlsx",
+  excludeColumns: ["id", "createdAt"], // Columns to skip
+  includeColumns: [{ key: "notes", header: "Notes" }] // Extra columns
+})
+```
+
+#### Importing Data
+
+Parses an uploaded Excel file into a raw JSON array. Does **not** handle validation or DB insertion.
+
+```tsx
+import { importFromExcel } from "@/components/client-table"
+
+const handleFileUpload = async (file: File) => {
+  const { data, errors } = await importFromExcel({
+    file,
+    columnMapping: { "Name": "name", "Role": "role" } // Optional header mapping
+  })
+  
+  if (errors.length > 0) {
+    console.error(errors)
+    return
+  }
+  
+  // Send `data` to your API/Service for validation and insertion
+  await saveUsers(data)
+}
+```
+
+## Types
+
+We use a custom column definition type to support our extended `meta` properties.
+
+```typescript
+import { ClientTableColumnDef } from "@/components/client-table"
+
+const columns: ClientTableColumnDef<MyData>[] = [ ... ]
+```
+
+Supported `meta` properties:
+
+- `filterType`: `"text" | "select" | "boolean"`
+- `filterOptions`: `{ label: string; value: string }[]` (Required for `select`)