@qijenchen/design-system 0.1.0-beta.81 → 0.1.0-beta.82

package/dist/components/DataTable/data-table.js

@@ -2,7 +2,8 @@ import { jsxs, jsx, Fragment } from "react/jsx-runtime";
 import * as React from "react";
 import { createPortal } from "react-dom";
 import { Empty } from "../Empty/empty.js";
-import { useReactTable, getExpandedRowModel, getSortedRowModel, getCoreRowModel, flexRender } from "@tanstack/react-table";
+import { Pagination } from "../Pagination/pagination.js";
+import { useReactTable, getPaginationRowModel, getExpandedRowModel, getSortedRowModel, getCoreRowModel, flexRender } from "@tanstack/react-table";
 import { useVirtualizer } from "@tanstack/react-virtual";
 import { TableScrollProvider } from "../Field/field-context.js";
 import { cva } from "class-variance-authority";
@@ -359,7 +360,7 @@ function DataTableInner({
   data,
   size = "md",
   autoRowHeight = false,
-  height = "400px",
+  height: heightProp,
   overscan = 5,
   emptyState,
   enableHover = true,
@@ -395,10 +396,12 @@ function DataTableInner({
   experimentalSpreadsheetOverlay = false,
   experimentalActiveEditorController = false,
   spreadsheetMode = false,
+  pagination,
   className,
   ...props
 }, ref) {
   var _a, _b, _c;
+  const height = heightProp ?? (pagination ? "auto" : "400px");
   const [editingCellId, setEditingCellId] = React.useState(null);
   const [editingDraft, setEditingDraft] = React.useState(void 0);
   const [selectedCellId, setSelectedCellId] = React.useState(null);
@@ -527,6 +530,14 @@ function DataTableInner({
     if (enabled && !out.includes(SELECT_COL_ID)) out.unshift(SELECT_COL_ID);
     return out;
   }, [userColumnOrder, enabled]);
+  const paginationEnabled = !!pagination;
+  const paginationOpts = typeof pagination === "object" ? pagination : void 0;
+  const [pageSizeState, setPageSizeState] = React.useState((paginationOpts == null ? void 0 : paginationOpts.pageSize) ?? 20);
+  const [currentPage, setCurrentPage] = useControllable({
+    value: paginationOpts == null ? void 0 : paginationOpts.page,
+    defaultValue: (paginationOpts == null ? void 0 : paginationOpts.defaultPage) ?? 1,
+    onChange: paginationOpts == null ? void 0 : paginationOpts.onPageChange
+  });
   const table = useReactTable({
     ...tableOptions,
     data,
@@ -537,7 +548,10 @@ function DataTableInner({
       ...tableOptions == null ? void 0 : tableOptions.state,
       // columnPinning + columnOrder 在 user state 後 override,確保 __select__ 永遠左
       columnPinning: { left: effectivePinnedLeft, right: pinnedRightColumns ?? [] },
-      ...effectiveColumnOrder ? { columnOrder: effectiveColumnOrder } : {}
+      ...effectiveColumnOrder ? { columnOrder: effectiveColumnOrder } : {},
+      // L5 分頁:必在 ...tableOptions?.state 之後 spread(同 columnPinning override 理由——
+      // 防 user state 蓋掉內建接線);頁碼變更由 <Pagination onPageChange> 驅動,不走 TanStack 內部 setter
+      ...paginationEnabled ? { pagination: { pageIndex: currentPage - 1, pageSize: pageSizeState } } : {}
     },
     enableMultiSort,
     // **#1 fix(2026-05-04)**:chain user `tableOptions.onSortingChange`(spread 在前被 override = 之前 bug)
@@ -557,6 +571,8 @@ function DataTableInner({
     getSortedRowModel: getSortedRowModel(),
     // L4 nested rows:啟用 expanded row model(consumer 透過 tableOptions.getSubRows + state.expanded forward)
     getExpandedRowModel: getExpandedRowModel(),
+    // L5 分頁:條件掛載(TanStack 官方:pagination 與 virtualization 為互斥替代策略)
+    ...paginationEnabled ? { getPaginationRowModel: getPaginationRowModel() } : {},
     getRowId,
     // 2026-05-06 v14 column resize:`onChange` mode → drag 中 column 即時跟動 cursor(world-class
     // canonical:TanStack docs / AG Grid / Excel / Google Sheets 全部 live resize)。前 v13.2
@@ -570,9 +586,11 @@ function DataTableInner({
     columnResizeMode: "onChange"
   });
   const columnSizingState = table.getState().columnSizing;
+  const isResizingColumn = table.getState().columnSizingInfo.isResizingColumn;
   const prevColumnSizingRef = React.useRef(columnSizingState);
   React.useEffect(() => {
     if (!onColumnResize) return;
+    if (isResizingColumn) return;
     const prev = prevColumnSizingRef.current;
     Object.keys(columnSizingState).forEach((id) => {
       if (columnSizingState[id] !== prev[id]) {
@@ -580,13 +598,18 @@ function DataTableInner({
       }
     });
     prevColumnSizingRef.current = columnSizingState;
-  }, [columnSizingState, onColumnResize]);
+  }, [columnSizingState, isResizingColumn, onColumnResize]);
   const { rows } = table.getRowModel();
   const isEmpty = rows.length === 0;
+  const pageCount = paginationEnabled ? table.getPageCount() : 0;
+  React.useEffect(() => {
+    if (!paginationEnabled) return;
+    if (pageCount > 0 && currentPage > pageCount) setCurrentPage(pageCount);
+  }, [paginationEnabled, pageCount, currentPage, setCurrentPage]);
   const hasHeightConstraint = height !== "auto";
   const isFillHeight = hasHeightConstraint && /^(100%|100vh|fill)$/.test(height);
   const VIRTUAL_THRESHOLD = 30;
-  const useVirtual = hasHeightConstraint && !isEmpty && rows.length > VIRTUAL_THRESHOLD;
+  const useVirtual = !paginationEnabled && hasHeightConstraint && !isEmpty && rows.length > VIRTUAL_THRESHOLD;
   const hasRowActions = !!rowActions;
   const tableRef = React.useRef(null);
   const bodyRef = React.useRef(null);
@@ -614,6 +637,7 @@ function DataTableInner({
     isScrollingResetDelay: 250
   });
   const [bodyMaxHeight, setBodyMaxHeight] = React.useState(null);
+  const paginationBarRef = React.useRef(null);
   React.useLayoutEffect(() => {
     var _a2;
     if (!isFillHeight) {
@@ -630,7 +654,9 @@ function DataTableInner({
       const slotH = (parentEl == null ? void 0 : parentEl.getBoundingClientRect().height) ?? tableRef.current.getBoundingClientRect().height;
       const headerEl = tableRef.current.firstElementChild;
       const headerH = (headerEl == null ? void 0 : headerEl.getBoundingClientRect().height) ?? 0;
-      const next = Math.max(0, slotH - headerH);
+      const barEl = paginationBarRef.current;
+      const barFootprint = barEl ? barEl.getBoundingClientRect().height + (parseFloat(getComputedStyle(barEl.parentElement).rowGap) || 0) : 0;
+      const next = Math.max(0, slotH - headerH - barFootprint);
       if (lastValue != null && Math.abs(next - lastValue) < 4) return;
       lastValue = next;
       pendingValue = next;
@@ -1188,6 +1214,9 @@ function DataTableInner({
         return;
       }
     },
+    // D3 dep-hygiene fix(2026-07-06):handler 內(portal edit Enter 分支)呼叫的是 canEditCell,
+    // 非 isCellEditable — 原 deps 列 isCellEditable 是靠 canEditCell identity-stable 才無實害的
+    // stale-closure 地雷;改列真實依賴 canEditCell(其 useCallback deps 已含 isCellEditable + isCellDisabled)。
     [
       enabled,
       mode,
@@ -1198,7 +1227,7 @@ function DataTableInner({
       selectedCellId,
       editingCellId,
       table,
-      isCellEditable
+      canEditCell
     ]
   );
   const headerCellEl = (header, showDivider) => {
@@ -1462,7 +1491,7 @@ function DataTableInner({
           "data-sortable-row-id": enableRowDrag ? row.id : void 0,
           "data-row-drag-source": enableRowDrag && isPrimaryRegion ? "true" : void 0,
           role: "row",
-          "aria-rowindex": idx + 2,
+          "aria-rowindex": (paginationEnabled ? (currentPage - 1) * pageSizeState : 0) + idx + 2,
           className: cn(
             "group/row flex relative",
             // H1 fix(2026-05-10):effectiveAutoRow 覆 global autoRowHeight,per-row 若有 cell error
@@ -1535,7 +1564,7 @@ function DataTableInner({
       className: cn(dataTableVariants({ bordered }), isFillHeight && "flex flex-col", "outline-none focus:outline-none focus-visible:outline-none", className),
       style: isFillHeight ? { maxHeight: height } : void 0,
       role: "table",
-      "aria-rowcount": rows.length + 1,
+      "aria-rowcount": (paginationEnabled ? table.getPrePaginationRowModel().rows.length : rows.length) + 1,
       tabIndex: enabled || spreadsheetMode ? 0 : void 0,
       onKeyDown: enabled || spreadsheetMode ? tableKeyboardHandler : void 0,
       onMouseOver: enterLeaveHandlers.onMouseOver,
@@ -1851,7 +1880,7 @@ function DataTableInner({
       const meta = (_a2 = table.getColumn(id)) == null ? void 0 : _a2.columnDef.meta;
       return !(meta == null ? void 0 : meta.locked);
     });
-  }, [table, columnsWithSelection, (_c = tableOptions == null ? void 0 : tableOptions.state) == null ? void 0 : _c.columnOrder]);
+  }, [table, columnsWithSelection, (_c = tableOptions == null ? void 0 : tableOptions.state) == null ? void 0 : _c.columnOrder, columnVisibility]);
   React.useEffect(() => {
     reorderableColumnIdsRef.current = reorderableColumnIds;
   }, [reorderableColumnIds]);
@@ -1910,6 +1939,33 @@ function DataTableInner({
     }
     return sameParentCollisionDetection(args);
   }, [sameParentCollisionDetection]);
+  const totalRowCount = paginationEnabled ? table.getPrePaginationRowModel().rows.length : 0;
+  const paginationBar = paginationEnabled && !isEmpty ? (
+    // 無條件 justify-end(2026-07-07 C16:原 paginationHasExtras 判斷式 = 平行重複 Pagination
+    // 內部 hasExtras 拼寫,未來加 extra 必 drift)——完整形態 Pagination 自帶 w-full
+    // justify-between,justify-end 對其為 no-op;純頁碼形態靠右 = 拍板 #6(shadcn justify-end /
+    // Ant Table bottomEnd / MUI / Carbon 4 家)。ref 供 isFillHeight bodyMaxHeight 扣 bar 高(C12)。
+    /* @__PURE__ */ jsx("div", { ref: paginationBarRef, className: "flex justify-end", children: /* @__PURE__ */ jsx(
+      Pagination,
+      {
+        total: totalRowCount,
+        page: currentPage,
+        onPageChange: setCurrentPage,
+        pageSize: pageSizeState,
+        onPageSizeChange: (next) => {
+          var _a2;
+          setPageSizeState(next);
+          (_a2 = paginationOpts == null ? void 0 : paginationOpts.onPageSizeChange) == null ? void 0 : _a2.call(paginationOpts, next);
+        },
+        showTotal: paginationOpts == null ? void 0 : paginationOpts.showTotal,
+        pageSizeOptions: paginationOpts == null ? void 0 : paginationOpts.pageSizeOptions
+      }
+    ) })
+  ) : null;
+  const composedContent = paginationBar ? /* @__PURE__ */ jsxs("div", { className: cn("flex flex-col gap-[var(--layout-space-tight)]", isFillHeight && "h-full min-h-0"), children: [
+    tableContent,
+    paginationBar
+  ] }) : tableContent;
   const wrapWithDnd = (node) => {
     if (!enableRowDrag && !enableColumnReorder) return node;
     return /* @__PURE__ */ jsxs(
@@ -1943,11 +1999,11 @@ function DataTableInner({
       {
         value: selection.mode === "include" ? selection.ids[0] ?? "" : "",
         onValueChange: (v) => v && setSelection({ mode: "include", ids: [v] }),
-        children: wrapWithDnd(tableContent)
+        children: wrapWithDnd(composedContent)
       }
     );
   }
-  return wrapWithDnd(tableContent);
+  return wrapWithDnd(composedContent);
 }
 const DataTable = React.forwardRef(DataTableInner);
 DataTable.displayName = "DataTable";
@@ -1957,7 +2013,9 @@ const dataTableMeta = {
   // non-family composite / overlay / layout
   variants: {},
   sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  // 'active' 移除 — 全檔無 Tailwind 按壓 utility(rg `active:` 僅命中 dnd-kit `e.active` 物件),
+  // 無按壓專屬視覺態;row action / drag handle 的按壓屬內嵌 Button meta(2026-07-07 對抗稽核補修)。
+  states: ["default", "hover", "focus-visible", "disabled"],
   tokens: {
     bg: ["bg-muted", "bg-neutral-hover", "bg-surface"],
     fg: ["text-fg-muted", "text-fg-secondary", "text-foreground"],