# ClientVirtualTable V3 Guide

This version introduces the `useClientTable` hook to drastically reduce boilerplate code and improve Developer Experience (DX).

## Key Changes from V2
- **`useClientTable` Hook**: Manages all state (sorting, filtering, pagination, grouping) and data fetching (Client or Server).
- **Cleaner Component**: `ClientVirtualTable` now accepts a `table` instance prop, making it a pure renderer.
- **Better Separation**: Logic is in the hook; UI is in the component.

## Usage

### 1. Client-Side Mode
Load all data once, let the hook handle the rest.

```tsx
import { useClientTable, ClientVirtualTable } from "@/components/client-table-v3";

function MyTable() {
  const [data, setData] = useState([]);
  
  // Load data...

  const { table, isLoading } = useClientTable({
    fetchMode: "client",
    data,
    columns,
    enablePagination: true, // Auto-enabled
  });

  return <ClientVirtualTable table={table} isLoading={isLoading} />;
}
```

### 2. Server-Side Mode (Factory Service)
Pass your server action as the `fetcher`. The hook handles debouncing and refetching.

```tsx
import { useClientTable, ClientVirtualTable } from "@/components/client-table-v3";
import { myServerAction } from "./actions";

function MyServerTable() {
  const { table, isLoading } = useClientTable({
    fetchMode: "server",
    fetcher: myServerAction, // Must accept TableState
    columns,
    enablePagination: true,
  });

  return <ClientVirtualTable table={table} isLoading={isLoading} />;
}
```

### 3. Server Grouping (Pattern 2-B)
The hook detects server-side grouping responses and provides them separately.

```tsx
const { table, isLoading, isServerGrouped, serverGroups } = useClientTable({
  fetchMode: "server",
  fetcher: myGroupFetcher,
  columns,
  enableGrouping: true,
});

if (isServerGrouped) {
  return <MyGroupRenderer groups={serverGroups} />;
}

return <ClientVirtualTable table={table} ... />;
```

## Hook Options (`useClientTable`)

| Option | Type | Description |
|--------|------|-------------|
| `fetchMode` | `'client' \| 'server'` | Default `'client'`. |
| `data` | `TData[]` | Data for client mode. |
| `fetcher` | `(state) => Promise` | Server action for server mode. |
| `columns` | `ColumnDef[]` | Column definitions. |
| `initialState` | `object` | Initial sorting, filters, etc. |
| `enablePagination` | `boolean` | Enable pagination logic. |
| `enableGrouping` | `boolean` | Enable grouping logic. |

## Component Props (`ClientVirtualTable`)

| Prop | Type | Description |
|------|------|-------------|
| `table` | `Table<TData>` | The table instance from the hook. |
| `isLoading` | `boolean` | Shows loading overlay. |
| `height` | `string` | Table height (required for virtualization). |
| `enableUserPreset` | `boolean` | Enable saving/loading view presets. |
| `tableKey` | `string` | Unique key for presets. |

## Migration from V2

1. Replace `<ClientVirtualTable ...props />` with `const { table } = useClientTable({...}); <ClientVirtualTable table={table} />`.
2. Remove local state (`sorting`, `pagination`, `useEffect` for fetching) from your page component.
3. Pass `fetcher` directly to the hook.