(김준회) 테이블 커스텀 훅 버전 생성

10 files changed, 1412 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.
+
+
diff --git a/components/client-table-v3/client-table-column-header.tsx b/components/client-table-v3/client-table-column-header.tsx
new file mode 100644
index 00000000..3be20565
--- /dev/null
+++ b/components/client-table-v3/client-table-column-header.tsx
@@ -0,0 +1,237 @@
+"use client"
+
+import * as React from "react"
+import { Header, Column } from "@tanstack/react-table"
+import { useSortable } from "@dnd-kit/sortable"
+import { CSS } from "@dnd-kit/utilities"
+import { flexRender } from "@tanstack/react-table"
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuTrigger,
+} from "@/components/ui/context-menu"
+import {
+  ArrowDown,
+  ArrowUp,
+  ChevronsUpDown,
+  EyeOff,
+  PinOff,
+  MoveLeft,
+  MoveRight,
+  Group,
+  Ungroup,
+} from "lucide-react"
+import { cn } from "@/lib/utils"
+import { ClientTableFilter } from "./client-table-filter"
+
+interface ClientTableColumnHeaderProps<TData, TValue>
+  extends React.HTMLAttributes<HTMLTableHeaderCellElement> {
+  header: Header<TData, TValue>
+  enableReordering?: boolean
+  renderHeaderVisualFeedback?: (props: {
+    column: Column<TData, TValue>
+    isPinned: boolean | string
+    isSorted: boolean | string
+    isFiltered: boolean
+    isGrouped: boolean
+  }) => React.ReactNode
+}
+
+export function ClientTableColumnHeader<TData, TValue>({
+  header,
+  enableReordering = true,
+  renderHeaderVisualFeedback,
+  className,
+  ...props
+}: ClientTableColumnHeaderProps<TData, TValue>) {
+  const column = header.column
+  const {
+    attributes,
+    listeners,
+    setNodeRef,
+    transform,
+    transition,
+    isDragging,
+  } = useSortable({
+    id: header.id,
+    disabled: !enableReordering || column.getIsResizing(),
+  })
+
+  // -- Styles --
+  const style: React.CSSProperties = {
+    // Apply transform only if reordering is enabled and active
+    transform: enableReordering ? CSS.Translate.toString(transform) : undefined,
+    transition: enableReordering ? transition : undefined,
+    width: header.getSize(),
+    zIndex: isDragging ? 100 : 0,
+    position: "relative",
+    ...props.style,
+  }
+
+  // Pinning Styles
+  const isPinned = column.getIsPinned()
+  const isSorted = column.getIsSorted()
+  const isFiltered = column.getFilterValue() !== undefined
+  const isGrouped = column.getIsGrouped()
+
+  if (isPinned === "left") {
+    style.left = `${column.getStart("left")}px`
+    style.position = "sticky"
+    style.zIndex = 30 // Pinned columns needs to be higher than normal headers
+  } else if (isPinned === "right") {
+    style.right = `${column.getAfter("right")}px`
+    style.position = "sticky"
+    style.zIndex = 30 // Pinned columns needs to be higher than normal headers
+  }
+
+  // -- Handlers --
+  const handleHide = () => column.toggleVisibility(false)
+  const handlePinLeft = () => column.pin("left")
+  const handlePinRight = () => column.pin("right")
+  const handleUnpin = () => column.pin(false)
+  const handleToggleGrouping = () => column.toggleGrouping()
+
+  // -- Content --
+  const content = (
+    <>
+      <div
+        className={cn(
+          "flex items-center gap-2",
+          column.getCanSort() ? "cursor-pointer select-none" : ""
+        )}
+        onClick={column.getToggleSortingHandler()}
+      >
+        {flexRender(column.columnDef.header, header.getContext())}
+        {column.getCanSort() && (
+          <span className="flex items-center">
+            {column.getIsSorted() === "desc" ? (
+              <ArrowDown className="h-4 w-4" />
+            ) : column.getIsSorted() === "asc" ? (
+              <ArrowUp className="h-4 w-4" />
+            ) : (
+              <ChevronsUpDown className="h-4 w-4 opacity-50" />
+            )}
+          </span>
+        )}
+        {isGrouped && <Group className="h-4 w-4 text-blue-500" />}
+      </div>
+
+      {/* Resize Handle */}
+      <div
+        onMouseDown={header.getResizeHandler()}
+        onTouchStart={header.getResizeHandler()}
+        onPointerDown={(e) => e.stopPropagation()}
+        onClick={(e) => e.stopPropagation()} // Prevent sort trigger
+        className={cn(
+          "absolute right-0 top-0 h-full w-2 cursor-col-resize select-none touch-none z-10",
+          "after:absolute after:right-0 after:top-0 after:h-full after:w-[1px] after:bg-border", // 시각적 구분선
+          "hover:bg-primary/20 hover:w-4 hover:-right-2", // 호버 시 클릭 영역 확장
+          header.column.getIsResizing() ? "bg-primary/50 w-1" : "bg-transparent"
+        )}
+      />
+
+      {/* Filter */}
+      {column.getCanFilter() && <ClientTableFilter column={column} />}
+
+      {/* Visual Feedback Indicators */}
+      {renderHeaderVisualFeedback ? (
+        renderHeaderVisualFeedback({
+          column,
+          isPinned,
+          isSorted,
+          isFiltered,
+          isGrouped,
+        })
+      ) : (
+        (isPinned || isFiltered || isGrouped) && (
+          <div className="absolute top-0.5 right-1 flex gap-1 z-10 pointer-events-none">
+            {isPinned && <div className="h-1.5 w-1.5 rounded-full bg-blue-500" />}
+            {isFiltered && <div className="h-1.5 w-1.5 rounded-full bg-yellow-500" />}
+            {isGrouped && <div className="h-1.5 w-1.5 rounded-full bg-green-500" />}
+          </div>
+        )
+      )}
+    </>
+  )
+
+  if (header.isPlaceholder) {
+    return (
+      <th
+        colSpan={header.colSpan}
+        style={style}
+        className={cn("border-b px-4 py-2 text-left text-sm font-medium bg-muted", className)}
+        {...props}
+      >
+        {null}
+      </th>
+    )
+  }
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>
+        <th
+          ref={setNodeRef}
+          colSpan={header.colSpan}
+          style={style}
+          className={cn(
+            "border-b px-4 py-2 text-left text-sm font-medium bg-muted group transition-colors",
+            isDragging ? "opacity-50 bg-accent" : "",
+            isPinned ? "shadow-[0_0_10px_rgba(0,0,0,0.1)]" : "",
+            className
+          )}
+          {...attributes}
+          {...listeners}
+          {...props}
+        >
+          {content}
+        </th>
+      </ContextMenuTrigger>
+      <ContextMenuContent className="w-48">
+        <ContextMenuItem onClick={handleHide}>
+          <EyeOff className="mr-2 h-4 w-4" />
+          Hide Column
+        </ContextMenuItem>
+
+        {column.getCanGroup() && (
+          <>
+            <ContextMenuSeparator />
+            <ContextMenuItem onClick={handleToggleGrouping}>
+              {isGrouped ? (
+                <>
+                  <Ungroup className="mr-2 h-4 w-4" />
+                  Ungroup
+                </>
+              ) : (
+                <>
+                  <Group className="mr-2 h-4 w-4" />
+                  Group by {column.id}
+                </>
+              )}
+            </ContextMenuItem>
+          </>
+        )}
+
+        <ContextMenuSeparator />
+        <ContextMenuItem onClick={handlePinLeft}>
+          <MoveLeft className="mr-2 h-4 w-4" />
+          Pin Left
+        </ContextMenuItem>
+        <ContextMenuItem onClick={handlePinRight}>
+          <MoveRight className="mr-2 h-4 w-4" />
+          Pin Right
+        </ContextMenuItem>
+        {isPinned && (
+          <ContextMenuItem onClick={handleUnpin}>
+            <PinOff className="mr-2 h-4 w-4" />
+            Unpin
+          </ContextMenuItem>
+        )}
+      </ContextMenuContent>
+    </ContextMenu>
+  )
+}
+
+
diff --git a/components/client-table-v3/client-table-filter.tsx b/components/client-table-v3/client-table-filter.tsx
new file mode 100644
index 00000000..eaf6b31e
--- /dev/null
+++ b/components/client-table-v3/client-table-filter.tsx
@@ -0,0 +1,103 @@
+"use client"
+
+import * as React from "react"
+import { Column } from "@tanstack/react-table"
+import { Input } from "@/components/ui/input"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+import { ClientTableColumnMeta } from "./types"
+
+interface ClientTableFilterProps<TData, TValue> {
+  column: Column<TData, TValue>
+}
+
+export function ClientTableFilter<TData, TValue>({
+  column,
+}: ClientTableFilterProps<TData, TValue>) {
+  const columnFilterValue = column.getFilterValue()
+  // Cast meta to our local type
+  const meta = column.columnDef.meta as ClientTableColumnMeta | undefined
+
+  // Handle Boolean Filter
+  if (meta?.filterType === "boolean") {
+    return (
+      <div onClick={(e) => e.stopPropagation()} className="mt-2">
+        <Select
+          value={(columnFilterValue as string) ?? "all"}
+          onValueChange={(value) =>
+            column.setFilterValue(value === "all" ? undefined : value === "true")
+          }
+        >
+          <SelectTrigger className="h-8 w-full">
+            <SelectValue placeholder="All" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">All</SelectItem>
+            <SelectItem value="true">Yes</SelectItem>
+            <SelectItem value="false">No</SelectItem>
+          </SelectContent>
+        </Select>
+      </div>
+    )
+  }
+
+  // Handle Select Filter (for specific options)
+  if (meta?.filterType === "select" && meta.filterOptions) {
+    return (
+      <div onClick={(e) => e.stopPropagation()} className="mt-2">
+        <Select
+          value={(columnFilterValue as string) ?? "all"}
+          onValueChange={(value) =>
+            column.setFilterValue(value === "all" ? undefined : value)
+          }
+        >
+          <SelectTrigger className="h-8 w-full">
+            <SelectValue placeholder="All" />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">All</SelectItem>
+            {meta.filterOptions.map((option) => (
+              <SelectItem key={option.value} value={option.value}>
+                {option.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+    )
+  }
+
+  // Default Text Filter
+  const [value, setValue] = React.useState(columnFilterValue)
+
+  React.useEffect(() => {
+    setValue(columnFilterValue)
+  }, [columnFilterValue])
+
+  React.useEffect(() => {
+    const timeout = setTimeout(() => {
+      column.setFilterValue(value)
+    }, 500)
+
+    return () => clearTimeout(timeout)
+  }, [value, column])
+
+  return (
+    <div onClick={(e) => e.stopPropagation()} className="mt-2">
+      <Input
+        type="text"
+        value={(value ?? "") as string}
+        onChange={(e) => setValue(e.target.value)}
+        placeholder="Search..."
+        className="h-8 w-full font-normal bg-background"
+      />
+    </div>
+  )
+}
+
+
diff --git a/components/client-table-v3/client-table-preset.tsx b/components/client-table-v3/client-table-preset.tsx
new file mode 100644
index 00000000..557e8493
--- /dev/null
+++ b/components/client-table-v3/client-table-preset.tsx
@@ -0,0 +1,189 @@
+"use client";
+
+import * as React from "react";
+import { Table } from "@tanstack/react-table";
+import { useSession } from "next-auth/react";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { Input } from "@/components/ui/input";
+import { Bookmark, Save, Trash2 } from "lucide-react";
+import {
+  getPresets,
+  savePreset,
+  deletePreset,
+} from "./preset-actions";
+import { Preset } from "./preset-types";
+import { toast } from "sonner"; 
+
+interface ClientTablePresetProps<TData> {
+  table: Table<TData>;
+  tableKey: string;
+}
+
+export function ClientTablePreset<TData>({
+  table,
+  tableKey,
+}: ClientTablePresetProps<TData>) {
+  const { data: session } = useSession();
+  const [savedPresets, setSavedPresets] = React.useState<Preset[]>([]);
+  const [isPresetDialogOpen, setIsPresetDialogOpen] = React.useState(false);
+  const [newPresetName, setNewPresetName] = React.useState("");
+  const [isLoading, setIsLoading] = React.useState(false);
+
+  const fetchSettings = React.useCallback(async () => {
+    const userIdVal = session?.user?.id;
+    if (!userIdVal) return;
+    
+    const userId = Number(userIdVal); 
+    if (isNaN(userId)) return;
+
+    const res = await getPresets(tableKey, userId);
+    if (res.success && res.data) {
+      setSavedPresets(res.data);
+    }
+  }, [session, tableKey]);
+
+  React.useEffect(() => {
+    if (session) {
+      fetchSettings();
+    }
+  }, [fetchSettings, session]);
+
+  const handleSavePreset = async () => {
+    const userIdVal = session?.user?.id;
+    if (!newPresetName.trim() || !userIdVal) return;
+    const userId = Number(userIdVal);
+    if (isNaN(userId)) return;
+
+    setIsLoading(true);
+    const state = table.getState();
+    const settingToSave = {
+      sorting: state.sorting,
+      columnFilters: state.columnFilters,
+      globalFilter: state.globalFilter,
+      columnVisibility: state.columnVisibility,
+      columnPinning: state.columnPinning,
+      columnOrder: state.columnOrder,
+      grouping: state.grouping,
+      pagination: { pageSize: state.pagination.pageSize }, 
+    };
+
+    const res = await savePreset(userId, tableKey, newPresetName, settingToSave);
+    setIsLoading(false);
+
+    if (res.success) {
+      toast.success("Preset saved successfully");
+      setIsPresetDialogOpen(false);
+      setNewPresetName("");
+      fetchSettings();
+    } else {
+      toast.error("Failed to save preset");
+    }
+  };
+
+  const handleLoadPreset = (preset: Preset) => {
+    const s = preset.setting as Record<string, any>;
+    if (!s) return;
+
+    if (s.sorting) table.setSorting(s.sorting);
+    if (s.columnFilters) table.setColumnFilters(s.columnFilters);
+    if (s.globalFilter !== undefined) table.setGlobalFilter(s.globalFilter);
+    if (s.columnVisibility) table.setColumnVisibility(s.columnVisibility);
+    if (s.columnPinning) table.setColumnPinning(s.columnPinning);
+    if (s.columnOrder) table.setColumnOrder(s.columnOrder);
+    if (s.grouping) table.setGrouping(s.grouping);
+    if (s.pagination?.pageSize) table.setPageSize(s.pagination.pageSize);
+    // Reset page index to avoid loading an out-of-range page after applying a preset
+    table.setPageIndex(0);
+    
+    toast.success(`Preset "${preset.name}" loaded`);
+  };
+
+  const handleDeletePreset = async (e: React.MouseEvent, id: string) => {
+    e.stopPropagation();
+    if (!confirm("Are you sure you want to delete this preset?")) return;
+
+    const res = await deletePreset(id);
+    if (res.success) {
+      toast.success("Preset deleted");
+      fetchSettings();
+    } else {
+      toast.error("Failed to delete preset");
+    }
+  };
+
+  if (!session) return null;
+
+  return (
+    <>
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="outline" size="sm" className="ml-2 hidden h-8 lg:flex">
+              <Bookmark className="mr-2 h-4 w-4" />
+              Presets
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-[200px]">
+            <DropdownMenuLabel>Saved Presets</DropdownMenuLabel>
+            <DropdownMenuSeparator />
+            {savedPresets.length === 0 ? (
+                <div className="p-2 text-sm text-muted-foreground text-center">No saved presets</div>
+            ) : (
+                savedPresets.map((preset) => (
+                    <DropdownMenuItem key={preset.id} onClick={() => handleLoadPreset(preset)} className="flex justify-between cursor-pointer">
+                        <span className="truncate flex-1">{preset.name}</span>
+                        <Button variant="ghost" size="icon" className="h-4 w-4" onClick={(e) => handleDeletePreset(e, preset.id)}>
+                            <Trash2 className="h-3 w-3 text-destructive" />
+                        </Button>
+                    </DropdownMenuItem>
+                ))
+            )}
+            <DropdownMenuSeparator />
+            <DropdownMenuItem onClick={() => setIsPresetDialogOpen(true)} className="cursor-pointer">
+                <Save className="mr-2 h-4 w-4" />
+                Save Current Preset
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+
+        <Dialog open={isPresetDialogOpen} onOpenChange={setIsPresetDialogOpen}>
+            <DialogContent>
+                <DialogHeader>
+                    <DialogTitle>Save Preset</DialogTitle>
+                    <DialogDescription>
+                        Save the current table configuration as a preset.
+                    </DialogDescription>
+                </DialogHeader>
+                <div className="grid gap-4 py-4">
+                    <Input 
+                        placeholder="Preset Name" 
+                        value={newPresetName} 
+                        onChange={(e) => setNewPresetName(e.target.value)}
+                    />
+                </div>
+                <DialogFooter>
+                    <Button variant="outline" onClick={() => setIsPresetDialogOpen(false)}>Cancel</Button>
+                    <Button onClick={handleSavePreset} disabled={isLoading}>Save</Button>
+                </DialogFooter>
+            </DialogContent>
+        </Dialog>
+    </>
+  );
+}
+
+
diff --git a/components/client-table-v3/client-virtual-table.tsx b/components/client-table-v3/client-virtual-table.tsx
new file mode 100644
index 00000000..7a092326
--- /dev/null
+++ b/components/client-table-v3/client-virtual-table.tsx
@@ -0,0 +1,309 @@
+"use client";
+
+import * as React from "react";
+import { Table, flexRender } from "@tanstack/react-table";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import {
+  DndContext,
+  closestCenter,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  DragEndEvent,
+} from "@dnd-kit/core";
+import {
+  arrayMove,
+  SortableContext,
+  horizontalListSortingStrategy,
+} from "@dnd-kit/sortable";
+import { cn } from "@/lib/utils";
+import { Loader2, ChevronRight, ChevronDown } from "lucide-react";
+
+import { ClientTableToolbar } from "../client-table/client-table-toolbar";
+import { exportToExcel } from "../client-table/export-utils";
+import { ClientDataTablePagination } from "@/components/client-data-table/data-table-pagination";
+import { ClientTableViewOptions } from "../client-table/client-table-view-options";
+
+import { ClientTableColumnHeader } from "./client-table-column-header";
+import { ClientTablePreset } from "./client-table-preset";
+import { ClientVirtualTableProps } from "./types";
+
+export function ClientVirtualTable<TData>({
+  table,
+  isLoading = false,
+  height = "100%",
+  estimateRowHeight = 40,
+  className,
+  actions,
+  customToolbar,
+  enableExport = true,
+  onExport,
+  enableUserPreset = false,
+  tableKey,
+  getRowClassName,
+  onRowClick,
+  renderHeaderVisualFeedback,
+}: ClientVirtualTableProps<TData>) {
+  // --- DnD Sensors ---
+  const sensors = useSensors(
+    useSensor(PointerSensor, {
+      activationConstraint: {
+        distance: 8,
+      },
+    }),
+    useSensor(KeyboardSensor)
+  );
+
+  // --- Drag Handler ---
+  const handleDragEnd = (event: DragEndEvent) => {
+    const { active, over } = event;
+    if (active && over && active.id !== over.id) {
+      const activeId = active.id as string;
+      const overId = over.id as string;
+
+      const activeColumn = table.getColumn(activeId);
+      const overColumn = table.getColumn(overId);
+
+      if (activeColumn && overColumn) {
+        const activePinState = activeColumn.getIsPinned();
+        const overPinState = overColumn.getIsPinned();
+
+        // If dragging between different pin states, update the pin state
+        if (activePinState !== overPinState) {
+          activeColumn.pin(overPinState);
+        }
+
+        // Reorder
+        const currentOrder = table.getState().columnOrder;
+        const oldIndex = currentOrder.indexOf(activeId);
+        const newIndex = currentOrder.indexOf(overId);
+        
+        if (oldIndex !== -1 && newIndex !== -1) {
+            table.setColumnOrder(arrayMove(currentOrder, oldIndex, newIndex));
+        }
+      }
+    }
+  };
+
+  // --- Virtualization ---
+  const tableContainerRef = React.useRef<HTMLDivElement>(null);
+  const { rows } = table.getRowModel();
+
+  const rowVirtualizer = useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => tableContainerRef.current,
+    estimateSize: () => estimateRowHeight,
+    overscan: 10,
+  });
+
+  const virtualRows = rowVirtualizer.getVirtualItems();
+  const totalSize = rowVirtualizer.getTotalSize();
+
+  const paddingTop = virtualRows.length > 0 ? virtualRows?.[0]?.start || 0 : 0;
+  const paddingBottom =
+    virtualRows.length > 0
+      ? totalSize - (virtualRows?.[virtualRows.length - 1]?.end || 0)
+      : 0;
+
+  // --- Export ---
+  const handleExport = async () => {
+    if (onExport) {
+      onExport(table.getFilteredRowModel().rows.map((r) => r.original));
+      return;
+    }
+    const currentData = table.getFilteredRowModel().rows.map((row) => row.original);
+    // Note: exportToExcel needs columns definition. table.getAllColumns() or visible columns?
+    // Using table.getAllLeafColumns() usually.
+    await exportToExcel(currentData, table.getAllLeafColumns(), `export-${new Date().toISOString().slice(0, 10)}.xlsx`);
+  };
+
+  const columns = table.getVisibleLeafColumns();
+  const data = table.getFilteredRowModel().rows; // or just rows which is from getRowModel
+
+  return (
+    <div
+      className={cn("flex flex-col gap-4", className)}
+      style={{ height }}
+    >
+      <ClientTableToolbar
+        globalFilter={table.getState().globalFilter ?? ""}
+        setGlobalFilter={table.setGlobalFilter}
+        totalRows={table.getRowCount()}
+        visibleRows={table.getRowModel().rows.length}
+        onExport={enableExport ? handleExport : undefined}
+        viewOptions={
+          <>
+            <ClientTableViewOptions table={table} />
+            {enableUserPreset && tableKey && (
+              <ClientTablePreset table={table} tableKey={tableKey} />
+            )}
+          </>
+        }
+        customToolbar={customToolbar}
+        actions={actions}
+      />
+
+      <div
+        ref={tableContainerRef}
+        className="relative border rounded-md overflow-auto bg-background flex-1 min-h-0"
+      >
+        {isLoading && (
+          <div className="absolute inset-0 z-50 flex items-center justify-center bg-background/50 backdrop-blur-sm">
+            <Loader2 className="h-8 w-8 animate-spin text-primary" />
+          </div>
+        )}
+
+        <DndContext
+          sensors={sensors}
+          collisionDetection={closestCenter}
+          onDragEnd={handleDragEnd}
+        >
+          <table
+            className="table-fixed border-collapse w-full min-w-full"
+            style={{ width: table.getTotalSize() }}
+          >
+            <thead className="sticky top-0 z-40 bg-muted">
+              {table.getHeaderGroups().map((headerGroup) => (
+                <tr key={headerGroup.id}>
+                  <SortableContext
+                    items={headerGroup.headers.map((h) => h.id)}
+                    strategy={horizontalListSortingStrategy}
+                  >
+                    {headerGroup.headers.map((header) => (
+                      <ClientTableColumnHeader
+                        key={header.id}
+                        header={header}
+                        enableReordering={true}
+                        renderHeaderVisualFeedback={renderHeaderVisualFeedback}
+                      />
+                    ))}
+                  </SortableContext>
+                </tr>
+              ))}
+            </thead>
+            <tbody>
+              {paddingTop > 0 && (
+                <tr>
+                  <td style={{ height: `${paddingTop}px` }} />
+                </tr>
+              )}
+              {virtualRows.length === 0 && !isLoading ? (
+                <tr>
+                  <td colSpan={columns.length} className="h-24 text-center">
+                    No results.
+                  </td>
+                </tr>
+              ) : (
+                virtualRows.map((virtualRow) => {
+                  const row = rows[virtualRow.index];
+
+                  // --- Group Header Rendering ---
+                  if (row.getIsGrouped()) {
+                    const groupingColumnId = row.groupingColumnId ?? "";
+                    const groupingValue = row.getGroupingValue(groupingColumnId);
+
+                    return (
+                      <tr
+                        key={row.id}
+                        className="hover:bg-muted/50 border-b bg-muted/30"
+                        style={{ height: `${virtualRow.size}px` }}
+                      >
+                        <td
+                          colSpan={columns.length}
+                          className="px-4 py-2 text-left font-medium cursor-pointer"
+                          onClick={row.getToggleExpandedHandler()}
+                        >
+                          <div className="flex items-center gap-2">
+                            {row.getIsExpanded() ? (
+                              <ChevronDown className="h-4 w-4" />
+                            ) : (
+                              <ChevronRight className="h-4 w-4" />
+                            )}
+                            <span className="flex items-center gap-2">
+                              <span className="font-bold capitalize">
+                                {groupingColumnId}:
+                              </span>
+                              <span>
+                                {String(groupingValue)}
+                              </span>
+                              <span className="text-muted-foreground text-sm font-normal">
+                                ({row.subRows.length})
+                              </span>
+                            </span>
+                          </div>
+                        </td>
+                      </tr>
+                    );
+                  }
+
+                  // --- Normal Row Rendering ---
+                  return (
+                    <tr
+                      key={row.id}
+                      className={cn(
+                        "hover:bg-muted/50 border-b last:border-0",
+                        getRowClassName ? getRowClassName(row.original, row.index) : "",
+                        onRowClick ? "cursor-pointer" : ""
+                      )}
+                      style={{ height: `${virtualRow.size}px` }}
+                      onClick={(e) => onRowClick?.(row, e)}
+                    >
+                      {row.getVisibleCells().map((cell) => {
+                        const isPinned = cell.column.getIsPinned();
+                        const isGrouped = cell.column.getIsGrouped();
+
+                        const style: React.CSSProperties = {
+                          width: cell.column.getSize(),
+                        };
+                        if (isPinned === "left") {
+                          style.position = "sticky";
+                          style.left = `${cell.column.getStart("left")}px`;
+                          style.zIndex = 20;
+                        } else if (isPinned === "right") {
+                          style.position = "sticky";
+                          style.right = `${cell.column.getAfter("right")}px`;
+                          style.zIndex = 20;
+                        }
+
+                        return (
+                          <td
+                            key={cell.id}
+                            className={cn(
+                              "px-2 py-0 text-sm truncate border-b bg-background",
+                              isGrouped ? "bg-muted/20" : ""
+                            )}
+                            style={style}
+                          >
+                            {cell.getIsGrouped() ? null : cell.getIsAggregated() ? (
+                              flexRender(
+                                cell.column.columnDef.aggregatedCell ??
+                                  cell.column.columnDef.cell,
+                                cell.getContext()
+                              )
+                            ) : cell.getIsPlaceholder() ? null : (
+                              flexRender(cell.column.columnDef.cell, cell.getContext())
+                            )}
+                          </td>
+                        );
+                      })}
+                    </tr>
+                  );
+                })
+              )}
+              {paddingBottom > 0 && (
+                <tr>
+                  <td style={{ height: `${paddingBottom}px` }} />
+                </tr>
+              )}
+            </tbody>
+          </table>
+        </DndContext>
+      </div>
+
+      <ClientDataTablePagination table={table} />
+    </div>
+  );
+}
+
+
diff --git a/components/client-table-v3/index.ts b/components/client-table-v3/index.ts
new file mode 100644
index 00000000..678a4757
--- /dev/null
+++ b/components/client-table-v3/index.ts
@@ -0,0 +1,9 @@
+export * from "./client-virtual-table";
+export * from "./use-client-table";
+export * from "./types";
+export * from "./client-table-column-header";
+export * from "./client-table-filter";
+export * from "./client-table-preset";
+export * from "./preset-types";
+
+
diff --git a/components/client-table-v3/preset-actions.ts b/components/client-table-v3/preset-actions.ts
new file mode 100644
index 00000000..3ef4d239
--- /dev/null
+++ b/components/client-table-v3/preset-actions.ts
@@ -0,0 +1,84 @@
+"use server";
+
+import db from "@/db/db";
+import { userCustomData } from "@/db/schema/user-custom-data/userCustomData";
+import { eq, and } from "drizzle-orm";
+import { Preset } from "./preset-types";
+
+export async function getPresets(tableKey: string, userId: number): Promise<{ success: boolean; data?: Preset[]; error?: string }> {
+  try {
+    const settings = await db
+      .select()
+      .from(userCustomData)
+      .where(
+        and(
+          eq(userCustomData.tableKey, tableKey),
+          eq(userCustomData.userId, userId)
+        )
+      )
+      .orderBy(userCustomData.createdDate);
+
+    const data: Preset[] = settings.map(s => ({
+      id: s.id,
+      name: s.customSettingName,
+      setting: s.customSetting,
+      createdAt: s.createdDate,
+      updatedAt: s.updatedDate,
+    }));
+
+    return { success: true, data };
+  } catch (error) {
+    console.error("Failed to fetch presets:", error);
+    return { success: false, error: "Failed to fetch presets" };
+  }
+}
+
+export async function savePreset(
+  userId: number,
+  tableKey: string,
+  name: string,
+  setting: any
+): Promise<{ success: boolean; error?: string }> {
+  try {
+    const existing = await db.query.userCustomData.findFirst({
+        where: and(
+            eq(userCustomData.userId, userId),
+            eq(userCustomData.tableKey, tableKey),
+            eq(userCustomData.customSettingName, name)
+        )
+    });
+
+    if (existing) {
+        await db.update(userCustomData)
+            .set({ 
+                customSetting: setting, 
+                updatedDate: new Date() 
+            })
+            .where(eq(userCustomData.id, existing.id));
+    } else {
+        await db.insert(userCustomData).values({
+            userId,
+            tableKey,
+            customSettingName: name,
+            customSetting: setting,
+        });
+    }
+
+    return { success: true };
+  } catch (error) {
+    console.error("Failed to save preset:", error);
+    return { success: false, error: "Failed to save preset" };
+  }
+}
+
+export async function deletePreset(id: string): Promise<{ success: boolean; error?: string }> {
+  try {
+    await db.delete(userCustomData).where(eq(userCustomData.id, id));
+    return { success: true };
+  } catch (error) {
+    console.error("Failed to delete preset:", error);
+    return { success: false, error: "Failed to delete preset" };
+  }
+}
+
+
diff --git a/components/client-table-v3/preset-types.ts b/components/client-table-v3/preset-types.ts
new file mode 100644
index 00000000..37177cff
--- /dev/null
+++ b/components/client-table-v3/preset-types.ts
@@ -0,0 +1,15 @@
+export interface Preset {
+  id: string;
+  name: string;
+  setting: any; // JSON object for table state
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface PresetRepository {
+  getPresets(tableKey: string, userId: number): Promise<{ success: boolean; data?: Preset[]; error?: string }>;
+  savePreset(userId: number, tableKey: string, name: string, setting: any): Promise<{ success: boolean; error?: string }>;
+  deletePreset(id: string): Promise<{ success: boolean; error?: string }>;
+}
+
+
diff --git a/components/client-table-v3/types.ts b/components/client-table-v3/types.ts
new file mode 100644
index 00000000..4f2d8c82
--- /dev/null
+++ b/components/client-table-v3/types.ts
@@ -0,0 +1,84 @@
+import {
+  ColumnDef,
+  RowData,
+  Table,
+  PaginationState,
+  SortingState,
+  ColumnFiltersState,
+  VisibilityState,
+  ColumnPinningState,
+  ColumnOrderState,
+  GroupingState,
+  ExpandedState,
+  RowSelectionState,
+  OnChangeFn,
+  Row,
+  Column,
+} from "@tanstack/react-table";
+
+// --- Column Meta ---
+export interface ClientTableColumnMeta {
+  filterType?: "text" | "select" | "boolean" | "date-range"; // Added date-range
+  filterOptions?: { label: string; value: string }[];
+  serverGroupable?: boolean; // For Pattern 2-B
+}
+
+export type ClientTableColumnDef<TData extends RowData, TValue = unknown> = ColumnDef<TData, TValue> & {
+  meta?: ClientTableColumnMeta;
+};
+
+// --- Fetcher Types ---
+export interface TableState {
+  pagination: PaginationState;
+  sorting: SortingState;
+  columnFilters: ColumnFiltersState;
+  globalFilter: string;
+  grouping: GroupingState;
+  expanded: ExpandedState;
+}
+
+export interface FetcherResult<TData> {
+  data: TData[];
+  totalRows: number;
+  pageCount?: number;
+  groups?: any[]; // For grouping response
+}
+
+export type TableFetcher<TData> = (
+  state: TableState,
+  additionalArgs?: any
+) => Promise<FetcherResult<TData>>;
+
+// --- Component Props ---
+export interface ClientVirtualTableProps<TData> {
+  table: Table<TData>;
+  isLoading?: boolean;
+  height?: string | number;
+  estimateRowHeight?: number;
+  className?: string;
+  
+  // UI Features
+  actions?: React.ReactNode;
+  customToolbar?: React.ReactNode;
+  enableExport?: boolean;
+  onExport?: (data: TData[]) => void;
+  
+  // Preset
+  enableUserPreset?: boolean;
+  tableKey?: string;
+
+  // Styling
+  getRowClassName?: (originalRow: TData, index: number) => string;
+  onRowClick?: (row: Row<TData>, event: React.MouseEvent) => void;
+  
+  // Visuals
+  renderHeaderVisualFeedback?: (props: {
+    column: Column<TData, unknown>;
+    isPinned: boolean | string;
+    isSorted: boolean | string;
+    isFiltered: boolean;
+    isGrouped: boolean;
+  }) => React.ReactNode;
+}
+
+
diff --git a/components/client-table-v3/use-client-table.ts b/components/client-table-v3/use-client-table.ts
new file mode 100644
index 00000000..87ce8a78
--- /dev/null
+++ b/components/client-table-v3/use-client-table.ts
@@ -0,0 +1,283 @@
+import * as React from "react";
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getGroupedRowModel,
+  getExpandedRowModel,
+  getFacetedRowModel,
+  getFacetedUniqueValues,
+  getFacetedMinMaxValues,
+  Table,
+  ColumnDef,
+  SortingState,
+  ColumnFiltersState,
+  PaginationState,
+  VisibilityState,
+  ColumnPinningState,
+  ColumnOrderState,
+  GroupingState,
+  ExpandedState,
+  RowSelectionState,
+  OnChangeFn,
+  FilterFn,
+} from "@tanstack/react-table";
+import { rankItem } from "@tanstack/match-sorter-utils";
+import { TableFetcher, FetcherResult } from "./types";
+
+// --- Utils ---
+const fuzzyFilter: FilterFn<any> = (row, columnId, value, addMeta) => {
+  const itemRank = rankItem(row.getValue(columnId), value);
+  addMeta({ itemRank });
+  return itemRank.passed;
+};
+
+// Simple debounce hook
+function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = React.useState(value);
+  React.useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+    return () => clearTimeout(handler);
+  }, [value, delay]);
+  return debouncedValue;
+}
+
+// --- Props ---
+export interface UseClientTableProps<TData, TValue> {
+  // Data Source
+  data?: TData[]; // For client mode
+  fetcher?: TableFetcher<TData>; // For server mode
+  fetchMode?: "client" | "server";
+
+  // Columns
+  columns: ColumnDef<TData, TValue>[];
+
+  // Options
+  enableGrouping?: boolean;
+  enablePagination?: boolean;
+  enableRowSelection?: boolean | ((row: any) => boolean);
+  enableMultiRowSelection?: boolean | ((row: any) => boolean);
+
+  // Initial State (Optional overrides)
+  initialState?: {
+    pagination?: PaginationState;
+    sorting?: SortingState;
+    columnFilters?: ColumnFiltersState;
+    globalFilter?: string;
+    columnVisibility?: VisibilityState;
+    columnPinning?: ColumnPinningState;
+    columnOrder?: ColumnOrderState;
+    grouping?: GroupingState;
+    expanded?: ExpandedState;
+    rowSelection?: RowSelectionState;
+  };
+
+  // Callbacks
+  onDataChange?: (data: TData[]) => void;
+  onError?: (error: any) => void;
+  
+  // Custom Row ID
+  getRowId?: (originalRow: TData, index: number, parent?: any) => string;
+}
+
+// --- Hook ---
+export function useClientTable<TData, TValue = unknown>({
+  data: initialData = [],
+  fetcher,
+  fetchMode = "client",
+  columns,
+  enableGrouping = false,
+  enablePagination = true,
+  enableRowSelection,
+  enableMultiRowSelection,
+  initialState,
+  onDataChange,
+  onError,
+  getRowId,
+}: UseClientTableProps<TData, TValue>) {
+  // 1. State Definitions
+  const [sorting, setSorting] = React.useState<SortingState>(initialState?.sorting ?? []);
+  const [columnFilters, setColumnFilters] = React.useState<ColumnFiltersState>(initialState?.columnFilters ?? []);
+  const [globalFilter, setGlobalFilter] = React.useState<string>(initialState?.globalFilter ?? "");
+  const [pagination, setPagination] = React.useState<PaginationState>(
+    initialState?.pagination ?? { pageIndex: 0, pageSize: 10 }
+  );
+  const [grouping, setGrouping] = React.useState<GroupingState>(initialState?.grouping ?? []);
+  const [expanded, setExpanded] = React.useState<ExpandedState>(initialState?.expanded ?? {});
+  const [rowSelection, setRowSelection] = React.useState<RowSelectionState>(initialState?.rowSelection ?? {});
+  const [columnVisibility, setColumnVisibility] = React.useState<VisibilityState>(initialState?.columnVisibility ?? {});
+  const [columnPinning, setColumnPinning] = React.useState<ColumnPinningState>(
+    initialState?.columnPinning ?? { left: [], right: [] }
+  );
+  const [columnOrder, setColumnOrder] = React.useState<ColumnOrderState>(
+    initialState?.columnOrder ?? columns.map((c) => c.id || (c as any).accessorKey) as string[]
+  );
+
+  // 2. Data State
+  const [data, setData] = React.useState<TData[]>(initialData);
+  const [totalRows, setTotalRows] = React.useState<number>(initialData.length);
+  const [pageCount, setPageCount] = React.useState<number>(-1);
+  const [isLoading, setIsLoading] = React.useState<boolean>(false);
+  
+  // Grouping specific data
+  // In Pattern 2-B, the server returns "groups" instead of flat data.
+  // We might need to store that separately or handle it within data if using TanStack's mix.
+  // For now, let's assume the fetcher returns a flat array or we handle groups manually in the component.
+  // But wait, client-virtual-table V2 handles groups by checking row.getIsGrouped().
+  // If fetchMode is server, and grouping is active, the server might return "groups".
+  // The V2 implementation handled this by setting `groups` state in the consumer and switching rendering.
+  // We want to encapsulate this.
+  const [serverGroups, setServerGroups] = React.useState<any[]>([]);
+  const [isServerGrouped, setIsServerGrouped] = React.useState(false);
+
+  const isServer = fetchMode === "server";
+
+  // Debounced states for fetching to avoid rapid-fire requests
+  const debouncedGlobalFilter = useDebounce(globalFilter, 300);
+  const debouncedColumnFilters = useDebounce(columnFilters, 300);
+  // Pagination and Sorting don't need debounce usually, but grouping might.
+
+  // 3. Data Fetching (Server Mode)
+  const refresh = React.useCallback(async () => {
+    if (!isServer || !fetcher) return;
+
+    setIsLoading(true);
+    try {
+      const result = await fetcher({
+        pagination,
+        sorting,
+        columnFilters: debouncedColumnFilters,
+        globalFilter: debouncedGlobalFilter,
+        grouping,
+        expanded,
+      });
+
+      if (result.groups) {
+        setServerGroups(result.groups);
+        setIsServerGrouped(true);
+        setData([]); // Clear flat data
+      } else {
+        setData(result.data);
+        setTotalRows(result.totalRows);
+        setPageCount(result.pageCount ?? -1);
+        setServerGroups([]);
+        setIsServerGrouped(false);
+        if (onDataChange) onDataChange(result.data);
+      }
+    } catch (err) {
+      console.error("Failed to fetch table data:", err);
+      if (onError) onError(err);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [
+    isServer,
+    fetcher,
+    pagination,
+    sorting,
+    debouncedColumnFilters,
+    debouncedGlobalFilter,
+    grouping,
+    expanded,
+    onDataChange,
+    onError,
+  ]);
+
+  // Initial fetch and refetch on state change
+  React.useEffect(() => {
+    if (isServer) {
+      refresh();
+    }
+  }, [refresh, isServer]);
+
+  // Update data when props change in Client Mode
+  React.useEffect(() => {
+    if (!isServer) {
+      setData(initialData);
+      setTotalRows(initialData.length);
+    }
+  }, [initialData, isServer]);
+
+  // 4. TanStack Table Instance
+  const table = useReactTable({
+    data,
+    columns,
+    state: {
+      sorting,
+      columnFilters,
+      globalFilter,
+      pagination,
+      columnVisibility,
+      columnPinning,
+      columnOrder,
+      rowSelection,
+      grouping,
+      expanded,
+    },
+    // Server-side Flags
+    manualPagination: isServer,
+    manualSorting: isServer,
+    manualFiltering: isServer,
+    manualGrouping: isServer,
+    
+    // Counts
+    pageCount: isServer ? pageCount : undefined,
+    rowCount: isServer ? totalRows : undefined,
+
+    // Handlers
+    onSortingChange: setSorting,
+    onColumnFiltersChange: setColumnFilters,
+    onGlobalFilterChange: setGlobalFilter,
+    onPaginationChange: setPagination,
+    onColumnVisibilityChange: setColumnVisibility,
+    onColumnPinningChange: setColumnPinning,
+    onColumnOrderChange: setColumnOrder,
+    onRowSelectionChange: setRowSelection,
+    onGroupingChange: setGrouping,
+    onExpandedChange: setExpanded,
+
+    // Configs
+    enableRowSelection,
+    enableMultiRowSelection,
+    enableGrouping,
+    getCoreRowModel: getCoreRowModel(),
+    
+    // Conditional Models (Client vs Server)
+    getFilteredRowModel: !isServer ? getFilteredRowModel() : undefined,
+    getFacetedRowModel: !isServer ? getFacetedRowModel() : undefined,
+    getFacetedUniqueValues: !isServer ? getFacetedUniqueValues() : undefined,
+    getFacetedMinMaxValues: !isServer ? getFacetedMinMaxValues() : undefined,
+    getSortedRowModel: !isServer ? getSortedRowModel() : undefined,
+    getGroupedRowModel: (!isServer && enableGrouping) ? getGroupedRowModel() : undefined,
+    getExpandedRowModel: (!isServer && enableGrouping) ? getExpandedRowModel() : undefined,
+    getPaginationRowModel: (!isServer && enablePagination) ? getPaginationRowModel() : undefined,
+    
+    columnResizeMode: "onChange",
+    filterFns: {
+      fuzzy: fuzzyFilter,
+    },
+    globalFilterFn: fuzzyFilter,
+    getRowId,
+  });
+
+  return {
+    table,
+    data,
+    totalRows,
+    isLoading,
+    isServerGrouped,
+    serverGroups,
+    refresh,
+    // State setters if needed manually
+    setSorting,
+    setColumnFilters,
+    setPagination,
+    setGlobalFilter,
+  };
+}
+
+