diff options
Diffstat (limited to 'components/client-table-v2')
| -rw-r--r-- | components/client-table-v2/GUIDE-v2.md | 93 | ||||
| -rw-r--r-- | components/client-table-v2/GUIDE-v3-ko.md | 92 | ||||
| -rw-r--r-- | components/client-table-v2/GUIDE-v3.md | 93 | ||||
| -rw-r--r-- | components/client-table-v2/GUIDE.md | 178 | ||||
| -rw-r--r-- | components/client-table-v2/adapter/create-table-service.ts | 101 | ||||
| -rw-r--r-- | components/client-table-v2/adapter/drizzle-table-adapter.ts | 173 | ||||
| -rw-r--r-- | components/client-table-v2/client-table-preset.tsx | 3 |
7 files changed, 733 insertions, 0 deletions
diff --git a/components/client-table-v2/GUIDE-v2.md b/components/client-table-v2/GUIDE-v2.md new file mode 100644 index 00000000..930123fb --- /dev/null +++ b/components/client-table-v2/GUIDE-v2.md @@ -0,0 +1,93 @@ +# ClientVirtualTable V2 — Server Fetching Guide + +This guide focuses on `fetchMode="server"` usage (Tabs 2, 2-B, 3 in `/[lng]/test/table-v2`). Client mode is unchanged from `GUIDE.md`. + +## Core Concepts +- `fetchMode="server"` sets `manualPagination|manualSorting|manualFiltering|manualGrouping` to true. The table **renders what the server returns**; no client-side sorting/filtering/pagination is applied. +- You must control table state (pagination, sorting, filters, grouping, globalFilter) in the parent and refetch on change. +- Provide `rowCount` (and optionally `pageCount`) so the pagination footer is accurate. +- Export uses the current row model; in server mode it only exports the loaded page unless you fetch everything yourself. + +## Minimal Wiring (Factory Service) +```tsx +const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 }); +const [sorting, setSorting] = useState([]); +const [columnFilters, setColumnFilters] = useState([]); +const [globalFilter, setGlobalFilter] = useState(""); +const [data, setData] = useState([]); +const [rowCount, setRowCount] = useState(0); +const [loading, setLoading] = useState(false); + +useEffect(() => { + const run = async () => { + setLoading(true); + const res = await getTableData({ + pagination, + sorting, + columnFilters, + globalFilter, + }); + setData(res.data); + setRowCount(res.totalRows); + setLoading(false); + }; + run(); +}, [pagination, sorting, columnFilters, globalFilter]); + +<ClientVirtualTable + fetchMode="server" + data={data} + rowCount={rowCount} + columns={columns} + isLoading={loading} + enablePagination + pagination={pagination} + onPaginationChange={setPagination} + sorting={sorting} + onSortingChange={setSorting} + columnFilters={columnFilters} + onColumnFiltersChange={setColumnFilters} + globalFilter={globalFilter} + onGlobalFilterChange={setGlobalFilter} +/> +``` + +## Using `createTableService` (Pattern 2) +- Import `createTableService` in a server action and pass `columns` (accessorKey-based) plus schema/db. +- The adapter maps `sorting`, `columnFilters`, `globalFilter`, `pagination` to Drizzle query parts. +- Returned shape: `{ data, totalRows, pageCount }`. Always forward `totalRows` to the client. + +## Custom Service (Pattern 3) +- Build custom joins manually; still read `tableState` for pagination/sorting/filtering if you need them. +- For sorting: map `tableState.sorting` IDs to your joined columns; provide a default order if none is set. +- Grouping in custom services requires manual implementation (see `getOrderTableDataGroupedByStatus` pattern). + +## Server Grouping (Pattern 2-B) +- Only columns marked `meta.serverGroupable` in server column defs should be used. +- Group headers are fetched via DB `GROUP BY`; expanded rows are fetched per group. +- When grouping is active, the table may render a custom grouped view instead of the virtual table; ensure your fetcher returns either `{ groups }` or `{ data, totalRows }`. + +## Presets in Server Mode +- Presets store: sorting, columnFilters, globalFilter, columnVisibility, columnPinning, columnOrder, grouping, pageSize. +- Loading a preset triggers the table’s `set*` APIs; parent `on*Change` handlers refetch with the restored state. +- The component resets pageIndex to 0 when applying a preset to avoid out-of-range requests after pageSize changes. +- Use unique `tableKey` per screen to avoid clashing presets across pages. + +## Common Pitfalls +- Forgetting `rowCount` → pagination shows wrong totals. +- Not reacting to `sorting`/`filters`/`grouping` changes in your effect → UI toggles with no data change. +- Mapping `sorting` IDs to columns incorrectly in custom services → server ignores the sort. +- Mixing client-side models with server mode: do not enable client `getSortedRowModel`/`getFilteredRowModel` for server fetches (the component already skips them when `fetchMode="server"`). + +## Feature Matrix (Server Mode) +- Sorting: Supported; must be implemented in the server fetcher. +- Filtering: Supported; column filters/global filter forwarded; implement in server. +- Pagination: Supported; manual; provide `rowCount`. +- Grouping: Client grouping is off in server mode; implement via server `GROUP BY` or custom grouped view. +- Column show/hide, pinning, reorder: Client-side only; state is preserved and sent to presets but does not affect server queries unless you opt to read it. +- Export: Exports the currently loaded rows; fetch all data yourself for full exports. + +## Debug Checklist +- Confirm `fetchMode="server"` and `rowCount` are set. +- Verify the parent effect depends on `pagination`, `sorting`, `columnFilters`, `globalFilter`, and (if used) `grouping`. +- In custom services, console/log the incoming `tableState` to confirm the UI is sending the intended state. diff --git a/components/client-table-v2/GUIDE-v3-ko.md b/components/client-table-v2/GUIDE-v3-ko.md new file mode 100644 index 00000000..9ec71065 --- /dev/null +++ b/components/client-table-v2/GUIDE-v3-ko.md @@ -0,0 +1,92 @@ +# ClientVirtualTable V3 가이드 (한국어) + +`components/client-table-v2` 테이블 컴포넌트와 `fetchMode="server"` 사용 시 주의점을 정리했습니다. + +## 모듈 맵 +- `client-virtual-table.tsx`: 코어 테이블(가상 스크롤, 컬럼 DnD, 핀/숨김, 프리셋, 툴바, 페이지네이션). +- `client-table-column-header.tsx`: 헤더 셀(정렬 토글, 필터 UI, 컨텍스트 메뉴: 핀/숨김/그룹/재정렬). +- `client-table-toolbar.tsx` (client-table): 검색, 내보내기, 뷰 옵션, 프리셋 엔트리. +- `client-table-view-options.tsx` (client-table): 컬럼 표시/숨김 토글. +- `client-table-filter.tsx`: 컬럼 필터 UI(text/select/boolean). +- `client-table-preset.tsx`: `tableKey`+사용자별 프리셋 저장/불러오기/삭제. +- 기타: `export-utils`, `import-utils`, `ClientDataTablePagination`(client-data-table). +- 서버 헬퍼: `adapter/create-table-service.ts`, `adapter/drizzle-table-adapter.ts`. +- 타입: `types.ts`, `preset-types.ts`. + +## 핵심 동작 (ClientVirtualTable) +- 가상 스크롤: `height` 필수, `estimateRowHeight` 기본 40. +- DnD: 컬럼 재배치, 핀 섹션 간 이동 시 핀 상태 동기화. +- 핀/숨김/순서: 클라이언트 상태(`columnVisibility`, `columnPinning`, `columnOrder`). +- 정렬/필터/페이지네이션/그룹핑 + - `fetchMode="client"`: TanStack 모델 사용. + - `fetchMode="server"`: manual 플래그 on, 클라이언트 모델 skip → **서버가 정렬/필터/페이징된 결과를 반환해야 함**. +- 내보내기: 현재 렌더된 행 기준. 서버 모드에서 전체 내보내기는 직접 `onExport`로 구현 필요. +- 프리셋: `enableUserPreset`+`tableKey` 설정 시 표시. 불러올 때 pageIndex를 0으로 리셋해 서버 모드에서 범위 오류 방지. + +## 주요 Props +- `fetchMode`: `"client"` | `"server"` (기본 `"client"`). +- 데이터: `data`, `rowCount?`, `pageCount?`. +- 상태/핸들러: + - 페이지: `pagination`, `onPaginationChange`, `enablePagination`, `manualPagination?`. + - 정렬: `sorting`, `onSortingChange`. + - 필터: `columnFilters`, `onColumnFiltersChange`, `globalFilter`, `onGlobalFilterChange`. + - 그룹핑: `grouping`, `onGroupingChange`, `expanded`, `onExpandedChange`, `enableGrouping`. + - 표시/핀/순서: `columnVisibility`, `columnPinning`, `columnOrder` 및 각 onChange. + - 선택: `enableRowSelection`, `enableMultiRowSelection`, `rowSelection`, `onRowSelectionChange`. +- UX: `actions`, `customToolbar`, `enableExport`, `onExport`, `renderHeaderVisualFeedback`, `getRowClassName`, `onRowClick`. +- 프리셋: `enableUserPreset`, `tableKey`. +- 메타: `meta`, `getRowId`. + +## 서버 페칭 패턴 +### 패턴 1: 클라이언트 모드 +- `fetchMode="client"`, 전체 데이터 전달. 정렬/필터/그룹핑은 브라우저에서 처리. + +### 패턴 2: Factory Service (`createTableService`) +- 서버 액션: `createTableService({ db, schema, columns, defaultWhere?, customQuery? })`. +- 어댑터가 `sorting`, `columnFilters`, `globalFilter`, `pagination`, `grouping`을 Drizzle `where/orderBy/limit/offset/groupBy`로 변환. +- 반환 `{ data, totalRows, pageCount }` → 클라이언트에서 `rowCount` 설정 필수. +- 클라이언트: `pagination/sorting/columnFilters/globalFilter` 제어 후 deps로 `useEffect` 재호출. + +### 패턴 2-B: 서버 그룹핑 +- `getProductTableDataWithGrouping` 예시: `grouping` 없으면 일반 페칭, 있으면 DB `GROUP BY` 후 `{ groups }` 반환. +- 서버 그룹핑 가능한 컬럼(`meta.serverGroupable`)만 사용. +- 그룹 확장 시 그룹 키별 하위 행을 추가 조회, 그룹 변경 시 확장 상태 초기화. +- 그룹뷰 렌더 시 가상 테이블 대신 커스텀 블록을 사용할 수 있음. + +### 패턴 3: 커스텀 서비스 +- 조인/파생 컬럼용. `tableState`를 읽어 정렬 ID를 조인 컬럼에 매핑, 정렬 없을 때 기본 정렬 제공. +- 필터/글로벌 필터는 직접 구현해야 함. +- 그룹핑도 수동 구현(`getOrderTableDataGroupedByStatus` 참고). + +## 상태 → 쿼리 매핑 (서버) +- 정렬: `tableState.sorting`(id, desc) → DB 컬럼 매핑, 모르는 id는 무시. +- 필터: 텍스트(ilike), 불리언, 숫자, 범위[min,max], 다중선택(IN) 지원. +- 글로벌 필터: 매핑된 컬럼 OR ilike. +- 페이지: pageIndex/pageSize → limit/offset, `rowCount` 반환. +- 그룹핑: 지원 컬럼만 `GROUP BY`. + +## 프리셋 (서버 호환) +- 저장: sorting, columnFilters, globalFilter, columnVisibility, columnPinning, columnOrder, grouping, pageSize. +- 불러오기: `table.set*` 호출 + pageIndex 0 리셋 → 상위 `on*Change` 핸들러에서 재페칭. +- 화면별 고유 `tableKey` 사용 권장. 세션 필요. + +## 기능 매트릭스 (서버 모드) +- 정렬: 지원 (서버 구현 필요) +- 필터: 지원 (서버 구현 필요) +- 페이지네이션: 지원 (manual, `rowCount` 필요) +- 그룹핑: 자동 미지원, 서버 그룹핑 또는 커스텀 뷰로 구현 +- 컬럼 숨김/핀/순서: 클라이언트 전용(시각용), 서버 쿼리에 자동 반영 안 함 +- 내보내기: 로드된 행만; 전체 내보내기는 커스텀 `onExport` 필요 + +## 구현 팁 +- `fetchMode="server"`일 때 `rowCount` 꼭 설정. +- `pagination/sorting/columnFilters/globalFilter/(grouping)` 변경 시마다 재페칭. +- 정렬 없을 때 서버 기본 정렬을 지정. +- 그룹 변경 시 확장 상태 초기화. +- `height`를 항상 지정(가상 스크롤 컨테이너 필요). + +## 빠른 예시 +- 클라이언트: `fetchMode="client"`, 전체 데이터 전달, 그룹핑 옵션 사용 가능. +- Factory 서버: `fetchMode="server"`, `createTableService`, 제어형 상태 + `rowCount`. +- 서버 그룹핑: `grouping`에 따라 `{ groups }` vs `{ data }` 반환, `serverGroupable` 컬럼만 허용. +- 커스텀 조인: 정렬 ID 직접 매핑, 필터/글로벌 직접 적용, `rowCount` 반환. diff --git a/components/client-table-v2/GUIDE-v3.md b/components/client-table-v2/GUIDE-v3.md new file mode 100644 index 00000000..21a1217d --- /dev/null +++ b/components/client-table-v2/GUIDE-v3.md @@ -0,0 +1,93 @@ +# ClientVirtualTable V3 Guide + +This guide documents the table components in `components/client-table-v2`, with an emphasis on server fetching (`fetchMode="server"`) and how supporting components fit together. + +## Module Map +- `client-virtual-table.tsx`: Core table (virtualized, DnD columns, pin/hide, presets hook point, toolbar, pagination). +- `client-table-column-header.tsx`: Header cell with sort toggle, filter UI, context menu (hide/pin/group/reorder hook). +- `client-table-toolbar.tsx` (from `components/client-table`): Search box, export button, view options, preset entry point. +- `client-table-view-options.tsx` (from `components/client-table`): Column visibility toggles. +- `client-table-filter.tsx`: Column filter UI (text/select/boolean). +- `client-table-preset.tsx`: Save/load/delete presets per `tableKey` + user. +- `client-table-save-view.tsx`, `client-table-preset.tsx`, `client-table-toolbar.tsx`: Preset and view controls. +- `client-virtual-table` dependencies: `ClientDataTablePagination` (`components/client-data-table`), `export-utils`, `import-utils`. +- Server helpers: `adapter/create-table-service.ts`, `adapter/drizzle-table-adapter.ts`. +- Types: `types.ts`, `preset-types.ts`. + +## Core Behaviors (ClientVirtualTable) +- Virtualization: `height` is required; `estimateRowHeight` defaults to 40. +- Drag & Drop: Columns reorder across pin sections; drag between pin states updates pinning. +- Pin/Hide/Reorder: Managed client-side; state is exposed via `columnVisibility`, `columnPinning`, `columnOrder`. +- Sorting/Filtering/Pagination/Grouping: + - `fetchMode="client"`: uses TanStack models (`getSortedRowModel`, `getFilteredRowModel`, `getPaginationRowModel`, etc.). + - `fetchMode="server"`: sets manual flags true and skips client models; **server must return already-sorted/filtered/paged data**. +- Export: Uses current row model; in server mode it exports only the loaded rows unless you supply all data yourself via `onExport`. +- Presets: When `enableUserPreset` and `tableKey` are set, toolbar shows the preset control; loading a preset resets pageIndex to 0 to avoid invalid pages on server mode. + +## Key Props (ClientVirtualTable) +- `fetchMode`: `"client"` | `"server"` (default `"client"`). +- Data: `data`, `rowCount?`, `pageCount?`. +- State + handlers (controlled or uncontrolled): + - Pagination: `pagination`, `onPaginationChange`, `enablePagination`, `manualPagination?`. + - Sorting: `sorting`, `onSortingChange`. + - Filters: `columnFilters`, `onColumnFiltersChange`, `globalFilter`, `onGlobalFilterChange`. + - Grouping: `grouping`, `onGroupingChange`, `expanded`, `onExpandedChange`, `enableGrouping`. + - Visibility/Pinning/Order: `columnVisibility`, `onColumnVisibilityChange`, `columnPinning`, `onColumnPinningChange`, `columnOrder`, `onColumnOrderChange`. + - Selection: `enableRowSelection`, `enableMultiRowSelection`, `rowSelection`, `onRowSelectionChange`. +- UX: `actions`, `customToolbar`, `enableExport`, `onExport`, `renderHeaderVisualFeedback`, `getRowClassName`, `onRowClick`. +- Presets: `enableUserPreset`, `tableKey`. +- Meta: `meta`, `getRowId`. + +## Server Fetching Patterns +### Pattern 1: Client-Side (baseline) +- `fetchMode="client"`, pass full dataset; TanStack handles sorting/filtering/grouping locally. + +### Pattern 2: Factory Service (`createTableService`) +- Server action: `createTableService({ db, schema, columns, defaultWhere?, customQuery? })`. +- The adapter maps `sorting`, `columnFilters`, `globalFilter`, `pagination`, `grouping` → Drizzle `where`, `orderBy`, `limit`, `offset`, `groupBy`. +- Returns `{ data, totalRows, pageCount }`; always forward `totalRows` to the client and wire `rowCount`. +- Client wiring: control `pagination`, `sorting`, `columnFilters`, `globalFilter`; refetch in `useEffect` on those deps. + +### Pattern 2-B: Server Grouping +- Uses `getProductTableDataWithGrouping` sample: if `grouping` is empty → normal server fetch; else returns `{ groups }` built from DB `GROUP BY`. +- Columns must be marked `meta.serverGroupable` in server column defs. +- Expanded groups fetch child rows per group key; grouping change clears expanded state. +- UI may render a custom grouped view (not the virtual table) when grouped. + +### Pattern 3: Custom Service +- For joins/derived columns: read `tableState` and manually map `sorting` IDs to joined columns; supply a default order when no sort is present. +- Filtering/global filter are not automatic—implement them if needed. +- Grouping is manual; see `getOrderTableDataGroupedByStatus` pattern for a grouped response shape. + +## State → Query Mapping (Server) +- Sorting: `tableState.sorting` (id, desc) → map to DB columns; ignore unknown ids. +- Filters: `columnFilters` supports text (ilike), boolean, number, range `[min,max]`, multi-select (IN). +- Global filter: ilike OR across mapped columns. +- Pagination: pageIndex/pageSize → limit/offset; return `rowCount`. +- Grouping: `grouping` → `GROUP BY` for supported columns only. + +## Presets (Server-Friendly) +- Saved keys: sorting, columnFilters, globalFilter, columnVisibility, columnPinning, columnOrder, grouping, pageSize. +- On load: applies `table.set*` and resets pageIndex to 0; parent `on*Change` handlers should trigger refetch. +- Use unique `tableKey` per screen to avoid collisions; requires authenticated session. + +## Feature Matrix (Server Mode) +- Sorting: Yes—server implemented. +- Filtering: Yes—server implemented. +- Pagination: Yes—manual; provide `rowCount`. +- Grouping: Not automatic; implement via server grouping or custom grouped view. +- Column hide/pin/reorder: Client-only (visual); does not change server query unless you opt to read it. +- Export: Only current rows unless you provide `onExport` with full data. + +## Implementation Tips +- Always set `rowCount` when `fetchMode="server"`. +- Refetch on `pagination`, `sorting`, `columnFilters`, `globalFilter`, and `grouping` (if used). +- Provide a default sort on the server when `sorting` is empty. +- Reset `expanded` or group expand state when grouping changes in server grouping flows. +- Ensure `height` is set; virtualization needs a scroll container. + +## Quick Examples +- Client: `fetchMode="client"` with `data` = full list; optional grouping enabled. +- Factory server: `fetchMode="server"`, `createTableService` action, controlled state with `rowCount`. +- Server grouping: `grouping` drives `{ groups }` vs `{ data }` response; only `serverGroupable` columns allowed. +- Custom join: Manually map `sorting` ids; apply filters/global; return `rowCount`. diff --git a/components/client-table-v2/GUIDE.md b/components/client-table-v2/GUIDE.md new file mode 100644 index 00000000..4ccadfc7 --- /dev/null +++ b/components/client-table-v2/GUIDE.md @@ -0,0 +1,178 @@ +# Table Component & Data Fetching Guide + +이 가이드는 `ClientVirtualTable`을 사용하여 테이블을 구현하고, 데이터를 페칭하는 3가지 주요 패턴을 설명합니다. + +## 개요 + +프로젝트의 복잡도와 요구사항에 따라 아래 3가지 패턴 중 하나를 선택하여 사용할 수 있습니다. + +| 모드 | 패턴 | 적합한 상황 | 특징 | +|---|---|---|---| +| **Client** | 1. Client-Side | 데이터가 적을 때 (< 1000건), 빠른 인터랙션 필요 | 전체 데이터 로드 후 브라우저에서 처리 | +| **Server** | 2. Factory Service | 단순 CRUD, 마스터 테이블 | 코드 1줄로 서버 액션 생성, 빠른 개발 | +| **Server** | 3. Custom Service | 복잡한 조인, 비즈니스 로직 | 완전한 쿼리 제어, Adapter를 도구로 사용 | + +--- + +## 1. Client-Side (기본 모드) + +데이터가 많지 않을 때 가장 간단한 방법입니다. 모든 데이터를 한 번에 받아와 `data` prop으로 넘깁니다. + +### 사용법 + +```tsx +// page.tsx +import { getAllUsers } from "@/lib/api/users"; +import { ClientVirtualTable } from "@/components/client-table-v2/client-virtual-table"; +import { columns } from "./columns"; + +export default async function UsersPage() { + const users = await getAllUsers(); // 전체 목록 조회 + + return ( + <ClientVirtualTable + fetchMode="client" + data={users} + columns={columns} + enablePagination + enableSorting + enableFiltering + /> + ); +} +``` + +--- + +## 2. Factory Service (추천 - 단순 조회용) + +`createTableService`를 사용하여 서버 사이드 페칭을 위한 액션을 자동으로 생성합니다. + +### 1) Server Action 생성 + +```typescript +// app/actions/user-table.ts +"use server" + +import { db } from "@/lib/db"; +import { users } from "@/lib/db/schema"; +import { columns } from "@/components/users/columns"; +import { createTableService } from "@/components/client-table-v2/adapter/create-table-service"; + +// 팩토리 함수로 액션 생성 (한 줄로 끝!) +export const getUserTableData = createTableService({ + db, + schema: users, + columns: columns +}); +``` + +### 2) 클라이언트 컴포넌트 연결 + +```tsx +// components/users/user-table.tsx +"use client" + +import { getUserTableData } from "@/app/actions/user-table"; +import { ClientVirtualTable } from "@/components/client-table-v2/client-virtual-table"; +import { columns } from "./columns"; +import { useState, useEffect } from "react"; + +export function UserTable() { + const [data, setData] = useState([]); + const [totalRows, setTotalRows] = useState(0); + const [loading, setLoading] = useState(false); + + // 테이블 상태 관리 + const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 }); + const [sorting, setSorting] = useState([]); + const [columnFilters, setColumnFilters] = useState([]); + const [globalFilter, setGlobalFilter] = useState(""); + + // 데이터 페칭 + useEffect(() => { + const fetchData = async () => { + setLoading(true); + const result = await getUserTableData({ + pagination, + sorting, + columnFilters, + globalFilter + }); + setData(result.data); + setTotalRows(result.totalRows); + setLoading(false); + }; + + fetchData(); + }, [pagination, sorting, columnFilters, globalFilter]); + + return ( + <ClientVirtualTable + fetchMode="server" + data={data} + rowCount={totalRows} + columns={columns} + isLoading={loading} + // 상태 연결 + pagination={pagination} onPaginationChange={setPagination} + sorting={sorting} onSortingChange={setSorting} + columnFilters={columnFilters} onColumnFiltersChange={setColumnFilters} + globalFilter={globalFilter} onGlobalFilterChange={setGlobalFilter} + /> + ); +} +``` + +--- + +## 3. Custom Service (복잡한 로직용) + +여러 테이블을 조인하거나, 특정 권한 체크 등 복잡한 로직이 필요할 때는 `DrizzleTableAdapter`를 직접 사용합니다. + +### 1) Custom Server Action 작성 + +```typescript +// app/actions/order-table.ts +"use server" + +import { db } from "@/lib/db"; +import { orders, users } from "@/lib/db/schema"; +import { DrizzleTableAdapter } from "@/components/client-table-v2/adapter/drizzle-table-adapter"; +import { count, eq } from "drizzle-orm"; + +export async function getOrderTableData(tableState) { + // 1. 어댑터로 조건절 생성 + const adapter = new DrizzleTableAdapter(orders, columns); + const { where, orderBy, limit, offset } = adapter.getQueryParts(tableState); + + // 2. 커스텀 쿼리 작성 (예: 유저 조인) + const data = await db + .select({ + orderId: orders.id, + amount: orders.amount, + userName: users.name // 조인된 컬럼 + }) + .from(orders) + .leftJoin(users, eq(orders.userId, users.id)) + .where(where) + .orderBy(...orderBy) + .limit(limit) + .offset(offset); + + // 3. 카운트 쿼리 + const total = await db + .select({ count: count() }) + .from(orders) + .where(where); + + return { + data, + totalRows: total[0]?.count ?? 0 + }; +} +``` + +### 2) 클라이언트 연결 + +Factory Service 방식과 동일하게 `useEffect`에서 `getOrderTableData`를 호출하면 됩니다. diff --git a/components/client-table-v2/adapter/create-table-service.ts b/components/client-table-v2/adapter/create-table-service.ts new file mode 100644 index 00000000..41c38906 --- /dev/null +++ b/components/client-table-v2/adapter/create-table-service.ts @@ -0,0 +1,101 @@ +import { PgTable } from "drizzle-orm/pg-core"; +import { DrizzleTableAdapter, DrizzleTableState } from "./drizzle-table-adapter"; +import { ColumnDef } from "@tanstack/react-table"; +import { SQL, and, count } from "drizzle-orm"; + +// Define a minimal DB interface that we need +// Adjust this to match your actual db instance type +interface DbInstance { + select: (args?: any) => any; +} + +export interface CreateTableServiceConfig<TData> { + /** + * Drizzle Database Instance + */ + db: DbInstance; + + /** + * Drizzle Table Schema (e.g. users, orders) + */ + schema: PgTable; // Using PgTable as base, works for most Drizzle tables + + /** + * React Table Columns Definition + * Used to map accessorKeys to DB columns + */ + columns: ColumnDef<TData, any>[]; + + /** + * Optional: Custom WHERE clause to always apply (e.g. deleted_at IS NULL) + */ + defaultWhere?: SQL; + + /** + * Optional: Custom query modifier + * Allows joining other tables or selecting specific fields + */ + customQuery?: (queryBuilder: any) => any; +} + +/** + * Factory function to create a standardized server action for a table. + * + * @example + * export const getUsers = createTableService({ + * db, + * schema: users, + * columns: userColumns + * }); + */ +export function createTableService<TData>(config: CreateTableServiceConfig<TData>) { + const { db, schema, columns, defaultWhere, customQuery } = config; + + // Return the actual Server Action function + return async function getTableData(tableState: DrizzleTableState) { + const adapter = new DrizzleTableAdapter(schema, columns); + const { where, orderBy, limit, offset, groupBy } = adapter.getQueryParts(tableState); + + // Merge defaultWhere with dynamic where + const finalWhere = defaultWhere + ? (where ? and(defaultWhere, where) : defaultWhere) + : where; + + // 1. Build Data Query + let dataQuery = db.select() + .from(schema) + .where(finalWhere) + .orderBy(...orderBy) + .limit(limit) + .offset(offset); + + if (groupBy && groupBy.length > 0) { + dataQuery = dataQuery.groupBy(...groupBy); + } + + // Apply custom query modifications (joins, etc) + if (customQuery) { + dataQuery = customQuery(dataQuery); + } + + // 2. Build Count Query + const countQuery = db.select({ count: count() }) + .from(schema) + .where(finalWhere); + + // Execute queries + // We use Promise.all to run them in parallel + const [data, countResult] = await Promise.all([ + dataQuery, + countQuery + ]); + + const totalRows = Number(countResult[0]?.count ?? 0); + + return { + data: data as TData[], + totalRows, + pageCount: Math.ceil(totalRows / (tableState.pagination?.pageSize ?? 10)) + }; + }; +} diff --git a/components/client-table-v2/adapter/drizzle-table-adapter.ts b/components/client-table-v2/adapter/drizzle-table-adapter.ts new file mode 100644 index 00000000..05bf4c5f --- /dev/null +++ b/components/client-table-v2/adapter/drizzle-table-adapter.ts @@ -0,0 +1,173 @@ +import { + ColumnFiltersState, + SortingState, + PaginationState, + GroupingState, + ColumnDef +} from "@tanstack/react-table"; +import { + SQL, + and, + or, + eq, + ilike, + gt, + lt, + gte, + lte, + inArray, + asc, + desc, + getTableColumns, +} from "drizzle-orm"; +import { PgTable, PgView, PgColumn } from "drizzle-orm/pg-core"; + +// Helper to detect if value is empty or undefined +const isEmpty = (value: any) => value === undefined || value === null || value === ""; + +export interface DrizzleTableState { + sorting?: SortingState; + columnFilters?: ColumnFiltersState; + globalFilter?: string; + pagination?: PaginationState; + grouping?: GroupingState; +} + +export class DrizzleTableAdapter<TData> { + private columnMap: Map<string, PgColumn>; + + constructor( + private table: PgTable | PgView, + private columns: ColumnDef<TData, any>[] + ) { + // Create a map of accessorKey -> Drizzle Column for fast lookup + this.columnMap = new Map(); + // @ts-ignore - getTableColumns works on views in newer drizzle versions or we can cast + const drizzleColumns = getTableColumns(table as any); + + columns.forEach(col => { + // We currently only support accessorKey which maps directly to a DB column + if ('accessorKey' in col && typeof col.accessorKey === 'string') { + const dbCol = drizzleColumns[col.accessorKey]; + if (dbCol) { + this.columnMap.set(col.accessorKey, dbCol); + } + } + }); + } + + private getColumn(columnId: string): PgColumn | undefined { + return this.columnMap.get(columnId); + } + + /** + * Build the WHERE clause based on column filters and global filter + */ + getWhere(columnFilters?: ColumnFiltersState, globalFilter?: string): SQL | undefined { + const conditions: SQL[] = []; + + // 1. Column Filters + if (columnFilters) { + for (const filter of columnFilters) { + const column = this.getColumn(filter.id); + if (!column) continue; + + const value = filter.value; + if (isEmpty(value)) continue; + + // Handle Array (range or multiple select) + if (Array.isArray(value)) { + // Range filter (e.g. [min, max]) + if (value.length === 2 && (typeof value[0] === 'number' || typeof value[0] === 'string')) { + const [min, max] = value; + if (!isEmpty(min) && !isEmpty(max)) { + conditions.push(and(gte(column, min), lte(column, max))!); + } else if (!isEmpty(min)) { + conditions.push(gte(column, min)!); + } else if (!isEmpty(max)) { + conditions.push(lte(column, max)!); + } + } + // Multi-select (IN) + else if (value.length > 0) { + conditions.push(inArray(column, value)!); + } + } + // Boolean + else if (typeof value === 'boolean') { + conditions.push(eq(column, value)!); + } + // Number + else if (typeof value === 'number') { + conditions.push(eq(column, value)!); + } + // String (Search) + else if (typeof value === 'string') { + conditions.push(ilike(column, `%${value}%`)!); + } + } + } + + // 2. Global Filter + if (globalFilter) { + const searchConditions: SQL[] = []; + this.columnMap.forEach((column) => { + // Implicitly supports only text-compatible columns for ilike + // Drizzle might throw if type mismatch, so user should be aware + searchConditions.push(ilike(column, `%${globalFilter}%`)); + }); + + if (searchConditions.length > 0) { + conditions.push(or(...searchConditions)!); + } + } + + return conditions.length > 0 ? and(...conditions) : undefined; + } + + /** + * Build the ORDER BY clause + */ + getOrderBy(sorting?: SortingState): SQL[] { + if (!sorting || !sorting.length) return []; + + return sorting.map((sort) => { + const column = this.getColumn(sort.id); + if (!column) return null; + return sort.desc ? desc(column) : asc(column); + }).filter(Boolean) as SQL[]; + } + + /** + * Build the GROUP BY clause + */ + getGroupBy(grouping?: GroupingState): SQL[] { + if (!grouping || !grouping.length) return []; + + return grouping.map(g => this.getColumn(g)).filter(Boolean) as SQL[]; + } + + /** + * Get Limit and Offset + */ + getPagination(pagination?: PaginationState) { + if (!pagination) return { limit: 10, offset: 0 }; + return { + limit: pagination.pageSize, + offset: pagination.pageIndex * pagination.pageSize, + }; + } + + /** + * Helper to apply all state to a query builder. + * Returns the modifier objects that can be passed to drizzle query builder. + */ + getQueryParts(state: DrizzleTableState) { + return { + where: this.getWhere(state.columnFilters, state.globalFilter), + orderBy: this.getOrderBy(state.sorting), + groupBy: this.getGroupBy(state.grouping), + ...this.getPagination(state.pagination) + }; + } +} diff --git a/components/client-table-v2/client-table-preset.tsx b/components/client-table-v2/client-table-preset.tsx index 64930e7a..21486c9b 100644 --- a/components/client-table-v2/client-table-preset.tsx +++ b/components/client-table-v2/client-table-preset.tsx @@ -108,6 +108,9 @@ export function ClientTablePreset<TData>({ 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, + // which is especially important in server-mode pagination. + table.setPageIndex(0); toast.success(`Preset "${preset.name}" loaded`); }; |