1 files changed, 99 insertions, 0 deletions
diff --git a/components/client-table-v3/GUIDE.md b/components/client-table-v3/GUIDE.md
new file mode 100644
index 00000000..05d7455e
--- /dev/null
+++ b/components/client-table-v3/GUIDE.md
@@ -0,0 +1,99 @@
+# 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.
+
+