import type { ColumnDef, ColumnFiltersState, FilterFn, OnChangeFn, PaginationState, Row, SortingState, Table, TableState, VisibilityState, } from "@tanstack/react-table"; import type React from "react"; import type { ReactNode } from "react"; import type { DataTableSavedView } from "./data-table-saved-views"; export type FacetedFilterConfig = { columnId: string; title: string; compact?: boolean; options: { label: string; value: string | number | boolean; icon?: React.ComponentType<{ className?: string }>; }[]; }; export interface DataTableProps { columns: ColumnDef[]; data: TData[]; // Styling Hooks className?: string; // Appended to table wrap containerClassName?: string; // Appended to outer wrapper /** * Appended to the scrollable box that wraps the table itself. * * Needed for `stickyHeader`: the box already scrolls horizontally, and CSS * forces the vertical axis to `auto` alongside it, so it — not the page — is * what a sticky header anchors to. Give it a height (e.g. `max-h-[70vh]`) or * the header has nothing to stick within and scrolls away with the page. */ tableContainerClassName?: string; /** ตรึงแถบเปลี่ยนหน้าไว้ล่างสุดของจอเสมอ ใช้คู่กับ `stickyHeader` */ stickyPagination?: boolean; // Accessibility & UI stickyHeader?: boolean; stickyEdgeColumns?: boolean; emptyStateComponent?: React.ReactNode; // Filters & Toolbar facetedFilters?: FacetedFilterConfig[]; actionsComponent?: (table: Table) => React.ReactNode; globalFilterKeys?: string[]; globalFilterFn?: FilterFn; globalFilterPlaceholder?: string; toolbarFilters?: (table: Table) => React.ReactNode; preservedFilterIds?: string[]; // State & Visibility initialVisibility?: VisibilityState; initialColumnFilters?: ColumnFiltersState; columnFilters?: ColumnFiltersState; initialState?: Partial; // Pagination & Sorting (Server-side support) pageCount?: number; rowCount?: number; /** * ควบคุม pagination จากภายนอก (ใช้คู่กับ manualPagination) * จำเป็นเมื่อ state จริงอยู่ที่อื่น เช่นใน URL — ไม่งั้นเลขหน้าใน UI จะไม่ตรงกับข้อมูลที่ server ส่งมา */ pagination?: PaginationState; /** ควบคุม sorting จากภายนอก (ใช้คู่กับ manualSorting) */ sorting?: SortingState; /** ควบคุมคำค้นจากภายนอก (ใช้คู่กับ manualFiltering) */ globalFilter?: string; /** * เรียกเมื่อผู้ใช้พิมพ์ในช่องค้นหา * ต้องส่งมาด้วยเมื่อเปิด manualFiltering ไม่งั้นช่องค้นหาจะไม่ทำอะไรเลย * เพราะ TanStack ถูกสั่งไม่ให้กรองเองแล้ว */ onGlobalFilterChange?: (value: string) => void; manualPagination?: boolean; manualSorting?: boolean; manualFiltering?: boolean; onPaginationChange?: OnChangeFn; onPageSizeChange?: (pageSize: number) => void; onSortingChange?: OnChangeFn; onColumnFiltersChange?: OnChangeFn; // Customization getRowClassName?: (row: Row) => string; /** * ข้อผิดพลาดของแถวนั้น (บันทึกไม่สำเร็จ, ส่งไม่ถึง) — คืนข้อความ = แถวขึ้นพื้นแดงและแสดงข้อความใต้เซลล์เนื้อหาแรก * คืนค่าว่าง = แถวปกติ · ทั้งตารางโหลดไม่สำเร็จใช้ `error` · `virtualized` ความสูงคงที่: ตั้ง `rowHeight` เผื่อบรรทัดนี้ */ getRowError?: (row: Row) => ReactNode; /** ปุ่ม "ลองใหม่" ต่อท้ายข้อความของ `getRowError` — ไม่ส่ง = ไม่มีปุ่ม */ onRowRetry?: (row: Row) => void; getSubRows?: (originalRow: TData) => TData[] | undefined; getRowId?: (originalRow: TData) => string; initialPageSize?: number; meta?: Record; isLoading?: boolean; /** ซ่อนแถบค้นหา/ตัวกรอง/View (ตารางตั้งค่าเล็ก ๆ) */ showToolbar?: boolean; /** ซ่อน pagination (แถวน้อย ไม่ต้องแบ่งหน้า) */ showPagination?: boolean; // Advanced enableColumnResizing?: boolean; enableRowSelection?: boolean | ((row: Row) => boolean); getFacetedUniqueValues?: (table: Table, columnId: string) => () => Map; pageSizeOptions?: number[]; onReorder?: (newData: TData[]) => void; renderCustomView?: (table: Table) => React.ReactNode; /** * `default` = เหมือนเดิม · `quiet` = "Calm toolbar, dense rows": ตัวกรองรวมเป็นปุ่มเดียว + ชิปที่ลบได้ในบรรทัดเดียวกับช่องค้นหา, * ตัวนับ "N จาก M รายการ" + สลับความหนาแน่น, หัวตารางเรียบ (ลูกศรเรียงโผล่เมื่อชี้), ช่องเลือก/ปุ่มท้ายแถวโผล่เมื่อชี้, * `StatusBadge` ในตารางเป็นจุดสี, แถวที่เลือกมีแถบสีซ้าย, แถบเลือกหมู่เป็นแคปซูล, เลขหน้าย่อ · * จอ < sm: ถ้ามีคอลัมน์ที่ใส่ `meta.mobile` จะแสดงเป็นรายการแถวละ 3 บรรทัดแทนตาราง (ดู `DataTableMobileSlot`) */ variant?: "default" | "quiet"; /** `quiet`: ความหนาแน่นเริ่มต้น (ผู้ใช้สลับได้ที่แถบเครื่องมือ) — ค่าเริ่มต้น comfortable */ defaultDensity?: "comfortable" | "compact"; /** * `quiet`: จำความหนาแน่นที่ผู้ใช้เลือกไว้ใน localStorage ด้วยคีย์นี้ (เช่น `"po-table-density"`) — * ไม่ส่ง = ไม่จำ (กลับเป็น `defaultDensity` ทุกครั้ง) · localStorage ใช้ไม่ได้ก็ทำงานต่อโดยไม่จำ */ densityStorageKey?: string; /** * มุมมองที่บันทึก (ตัวกรอง/คำค้น/การเรียง/คอลัมน์ที่ซ่อน/ความหนาแน่น): ส่ง `savedViews` + `onSavedViewsChange` ให้แอปเก็บเอง * (เช่นบน server ต่อผู้ใช้) หรือส่ง `savedViewsStorageKey` ให้เก็บใน localStorage — ส่งอย่างใดอย่างหนึ่ง = แสดงตัวเลือกมุมมองในแถบเครื่องมือ */ /** * ตารางเสมือน: แสดงทุกแถวที่ผ่านตัวกรอง (ไม่แบ่งหน้า ซ่อนเลขหน้า) แต่สร้าง DOM เฉพาะแถวที่เห็น — แถวนับพันไม่ค้าง * ต้องการกล่องที่สูงจำกัด (`tableContainerClassName` ค่าเริ่มต้น `max-h-[70vh]`) และแถวสูงคงที่ (`rowHeight`) * ข้อจำกัด: Ctrl+F ของเบราว์เซอร์เจอเฉพาะแถวที่สร้าง · ไม่ใช้ร่วมกับ `onReorder` (เปิดคู่กัน = ไม่เสมือน) * · รายการมือถือของ `quiet` เป็นเสมือนแบบเลื่อนทั้งหน้า (วัดความสูงแถวจริง) */ virtualized?: boolean; /** ความสูงแถวของตารางเสมือน (px) — ค่าเริ่มต้น 44 (quiet compact 36) */ rowHeight?: number; savedViews?: DataTableSavedView[]; onSavedViewsChange?: (views: DataTableSavedView[]) => void; savedViewsStorageKey?: string; /** มุมมองที่เลือกอยู่ (controlled) — null = "ทั้งหมด" */ activeViewId?: string | null; onActiveViewChange?: (id: string | null) => void; /** ชื่อชนิดข้อมูลสำหรับสถานะว่าง เช่น "ใบสั่งซื้อ" → "ยังไม่มีใบสั่งซื้อ" (`quiet`) */ resourceName?: string; /** `quiet`: ปุ่ม/ลิงก์ในสถานะ "ว่างจริง" (ไม่มีข้อมูลและไม่มีตัวกรอง) เช่น ปุ่ม "สร้างใบสั่งซื้อ" — ไม่ส่ง = ไม่มีปุ่ม */ emptyAction?: React.ReactNode; /** โหลดไม่สำเร็จ: แสดงสถานะผิดพลาดแทนตาราง (ทั้งสอง variant) — ข้อความกลาง ๆ ไม่แสดง error ดิบ */ error?: boolean; /** ปุ่ม "ลองใหม่" ของสถานะผิดพลาด — ไม่ส่ง = ไม่มีปุ่ม */ onRetry?: () => void; /** `quiet`: ปุ่มคำสั่งในแคปซูลเลือกหมู่ (ส่งออก/ลบ …) — ไม่ส่ง = แคปซูลมีแค่จำนวนที่เลือกและปุ่มล้าง */ selectionActions?: (table: Table) => React.ReactNode; /** * จอ < md แสดงมุมมองนี้ (การ์ด/รายการที่แอปทำเอง) แทนตาราง — ตัวกรอง/การเรียง/การแบ่งหน้าใช้ร่วมกัน * ไม่ต้องประกาศ `meta.mobile` · มีค่า = ใช้แทนรายการอัตโนมัติของ `quiet` · ตอนโหลดไม่สำเร็จ (`error`) ยังแสดงตาราง */ mobileView?: (table: Table) => React.ReactNode; /** แถบคำสั่งของแถวที่เลือกที่แอปทำเอง — วางระหว่างตารางกับการแบ่งหน้า (ทุก variant) */ selectionBar?: (table: Table) => React.ReactNode; /** ตัวกรองอยู่ในปุ่ม "ตัวกรอง" เสมอ แม้จอกว้าง (variant default) */ collapseFilters?: boolean; /** * แก้เซลล์ (`meta.editable`) ด้วยคีย์บอร์ดแบบ spreadsheet (จอกว้าง): ลูกศร = เลื่อนไปเซลล์ที่แก้ได้ข้างเคียง, * พิมพ์ = แก้โดยแทนค่าเดิม, F2/Enter = แก้ค่าเดิม, Delete = ล้าง · ขณะแก้: Enter = บันทึกแล้วลง (Shift = ขึ้น), * Tab = บันทึกแล้วไปขวา (Shift = ซ้าย), Esc = ยกเลิก · ค่าเริ่มต้น false */ cellNavigation?: boolean; } /** * `variant="quiet"` บนจอ < sm: วางที่ `columnDef.meta = { mobile: "title" }` — ชื่อบรรทัดแรกซ้าย · `end` ยอด/ตัวเลข บรรทัดแรกขวา · * `sub` บรรทัดรอง · `status` บรรทัดสถานะ (ต่อท้ายด้วย `meta`) · `meta` ข้อความเล็กต่อท้ายสถานะ · `hidden` ไม่แสดงบนมือถือ * ไม่ประกาศ slot ใดเลย = แสดงตารางเลื่อนแนวนอนเหมือนเดิม */ export type DataTableMobileSlot = "title" | "end" | "sub" | "status" | "meta" | "hidden";