# 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`)