@qijenchen/design-system 0.1.0-beta.80 → 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";
@@ -122,12 +123,11 @@ function SourceRowProvider({
     droppable.setNodeRef(el);
   }, [draggable.setNodeRef, droppable.setNodeRef]);
   const isDragging = draggable.isDragging;
-  const style = { ...dragSourceStyle(isDragging) };
   const handleAttrs = draggable.attributes;
-  const ctxValue = {
+  const ctxValue = React.useMemo(() => ({
     setNodeRef: setRefs,
     role,
-    style,
+    style: { ...dragSourceStyle(isDragging) },
     attributes: {},
     isDragging,
     // row 不接 listeners(button-only),baseRowDiv `{...(extra?.listeners ?? {})}` 自動 noop
@@ -140,7 +140,7 @@ function SourceRowProvider({
     handleListeners: draggable.listeners,
     handleAttributes: handleAttrs,
     invalidDrop
-  };
+  }), [setRefs, role, isDragging, draggable.setActivatorNodeRef, draggable.listeners, handleAttrs, invalidDrop]);
   return /* @__PURE__ */ jsx(SortableRowCtx.Provider, { value: ctxValue, children: children(ctxValue) });
 }
 function MirrorRowProvider({
@@ -154,7 +154,7 @@ function MirrorRowProvider({
   const droppable = useDroppable({ id, disabled, data: { type: "row" } });
   const dndCtx = useDndContext();
   const isDragging = ((_a = dndCtx.active) == null ? void 0 : _a.id) === id;
-  const ctxValue = {
+  const ctxValue = React.useMemo(() => ({
     setNodeRef: droppable.setNodeRef,
     role,
     style: { ...dragSourceStyle(isDragging) },
@@ -166,7 +166,7 @@ function MirrorRowProvider({
     handleListeners: void 0,
     handleAttributes: {},
     invalidDrop
-  };
+  }), [droppable.setNodeRef, role, isDragging, invalidDrop]);
   return /* @__PURE__ */ jsx(SortableRowCtx.Provider, { value: ctxValue, children: children(ctxValue) });
 }
 function DraggableHeaderCell({
@@ -220,12 +220,11 @@ function RowDragHandle({ disabled, anyDragActive }) {
       const rRect = rowEl.getBoundingClientRect();
       const tRect = tableEl.getBoundingClientRect();
       const rowHovered = rowEl.hasAttribute("data-hovered");
-      setPos({
-        top: rRect.top + rRect.height / 2,
-        left: tRect.left,
-        // table outer 左 border line position(viewport coords)
-        rowHovered
-      });
+      const top = rRect.top + rRect.height / 2;
+      const left = tRect.left;
+      setPos(
+        (prev) => prev && prev.top === top && prev.left === left && prev.rowHovered === rowHovered ? prev : { top, left, rowHovered }
+      );
     };
     update();
     const observer = new MutationObserver(update);
@@ -281,9 +280,10 @@ function RowDragHandle({ disabled, anyDragActive }) {
         // 2026-05-12 fix v2(user 抓「drag column sort 啟用時 button 不是 disable 視覺」):
         // 前 Round 4.5 加 `aria-disabled:opacity-[var(--opacity-disabled)]` 在 Button cva
         // 沒生效 — 因為 inline style `opacity` 永遠 win over Tailwind class。Fix:把 disabled
-        // state opacity 也 compute 進 inline style。priority order:invisible 0 → drag 0.5 →
-        // canDrag=false(sort active)disabled visual var(--opacity-disabled) 0.45 → idle 1。
-        opacity: visible ? ctx.isDragging ? 0.5 : canDrag ? 1 : "var(--opacity-disabled)" : 0,
+        // state opacity 也 compute 進 inline style。priority order:invisible 0 → drag var(--opacity-disabled)
+        // 0.45(2026-07-04 修:原硬寫 0.5 違 lib/drag-visual.ts SSOT)→ canDrag=false(sort active)
+        // disabled visual var(--opacity-disabled) 0.45 → idle 1。
+        opacity: visible ? ctx.isDragging ? "var(--opacity-disabled)" : canDrag ? 1 : "var(--opacity-disabled)" : 0,
         pointerEvents: visible ? "auto" : "none",
         transition: "opacity 150ms ease"
       },
@@ -315,12 +315,52 @@ function RowDragHandle({ disabled, anyDragActive }) {
     portalTarget && createPortal(wrapped, portalTarget)
   ] });
 }
+const EMPTY_META = {};
+const MemoCellSlot = React.memo(function MemoCellSlot2({
+  Cell,
+  rowId,
+  colId,
+  value,
+  meta,
+  mode,
+  size,
+  autoRowHeight,
+  isEditable,
+  isDisabled,
+  onCommitCell,
+  onCancelCell,
+  onCellCommitLive,
+  onEnterEdit
+}) {
+  const onCommit = React.useCallback((next) => onCommitCell(rowId, colId, next), [onCommitCell, rowId, colId]);
+  const onCommitLive = React.useCallback((next) => onCellCommitLive == null ? void 0 : onCellCommitLive(rowId, colId, next), [onCellCommitLive, rowId, colId]);
+  const onCancel = React.useCallback(() => onCancelCell(rowId, colId), [onCancelCell, rowId, colId]);
+  const onRequestEdit = React.useCallback(() => {
+    if (!isDisabled) onEnterEdit(rowId, colId);
+  }, [onEnterEdit, isDisabled, rowId, colId]);
+  return /* @__PURE__ */ jsx(
+    Cell,
+    {
+      value,
+      meta,
+      mode,
+      size,
+      autoRowHeight,
+      isEditable,
+      isDisabled,
+      onCommit,
+      onCommitLive,
+      onCancel,
+      onRequestEdit
+    }
+  );
+});
 function DataTableInner({
   columns,
   data,
   size = "md",
   autoRowHeight = false,
-  height = "400px",
+  height: heightProp,
   overscan = 5,
   emptyState,
   enableHover = true,
@@ -356,16 +396,14 @@ 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 exitEdit = React.useCallback(() => {
-    setEditingCellId(null);
-    setEditingDraft(void 0);
-  }, []);
   const [selectedCellId, setSelectedCellId] = React.useState(null);
   const [rangeAnchor, setRangeAnchor] = React.useState(null);
   const [rangeFocus, setRangeFocus] = React.useState(null);
@@ -384,14 +422,36 @@ function DataTableInner({
     document.addEventListener("pointerdown", handler, true);
     return () => document.removeEventListener("pointerdown", handler, true);
   }, [spreadsheetMode, selectedCellId, rangeAnchor]);
+  const restoreCellSelection = React.useCallback((rowId, colId) => {
+    if (!spreadsheetMode) return;
+    const cellId = `${rowId}:${colId}`;
+    setSelectedCellId(cellId);
+    setRangeAnchor(cellId);
+    setRangeFocus(null);
+    requestAnimationFrame(() => {
+      const el = tableRef.current;
+      if (!el) return;
+      const active = document.activeElement;
+      if (active === document.body || active === null) el.focus({ preventScroll: true });
+    });
+  }, [spreadsheetMode]);
   const commitCell = React.useCallback(
     (rowId, colId, next) => {
       onCellCommit == null ? void 0 : onCellCommit(rowId, colId, next);
       setEditingCellId(null);
       setEditingDraft(void 0);
+      restoreCellSelection(rowId, colId);
     },
-    [onCellCommit]
+    [onCellCommit, restoreCellSelection]
   );
+  const cancelCellEdit = React.useCallback((rowId, colId) => {
+    setEditingCellId(null);
+    setEditingDraft(void 0);
+    restoreCellSelection(rowId, colId);
+  }, [restoreCellSelection]);
+  const enterCellEdit = React.useCallback((rowId, colId) => {
+    setEditingCellId(cellEditId(rowId, colId));
+  }, []);
   const isCellEditable = React.useCallback(
     // any-allow: free-form consumer meta — same rationale as L143 renderTypedValue
     (meta, row) => {
@@ -470,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,
@@ -480,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)
@@ -500,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
@@ -513,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]) {
@@ -523,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);
@@ -557,6 +637,7 @@ function DataTableInner({
     isScrollingResetDelay: 250
   });
   const [bodyMaxHeight, setBodyMaxHeight] = React.useState(null);
+  const paginationBarRef = React.useRef(null);
   React.useLayoutEffect(() => {
     var _a2;
     if (!isFillHeight) {
@@ -573,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;
@@ -700,19 +783,22 @@ function DataTableInner({
       const Cell = resolveCellComponent(colType);
       const cellMode = experimentalActiveEditorController && isEditingThisCell ? "display" : isEditingThisCell && !disabled ? "edit" : "display";
       content = /* @__PURE__ */ jsx(
-        Cell,
+        MemoCellSlot,
         {
+          Cell,
+          rowId,
+          colId,
           value: cell.getValue(),
-          meta: meta ?? {},
+          meta: meta ?? EMPTY_META,
           mode: cellMode,
           size,
           autoRowHeight,
           isEditable: editable,
           isDisabled: disabled,
-          onCommit: (next) => commitCell(rowId, colId, next),
-          onCommitLive: (next) => onCellCommit == null ? void 0 : onCellCommit(rowId, colId, next),
-          onCancel: exitEdit,
-          onRequestEdit: () => !disabled && setEditingCellId(cellEditId(rowId, colId))
+          onCommitCell: commitCell,
+          onCancelCell: cancelCellEdit,
+          onCellCommitLive: onCellCommit,
+          onEnterEdit: enterCellEdit
         }
       );
     } else {
@@ -751,7 +837,7 @@ function DataTableInner({
       const rowId = cell.row.id;
       const rowOriginal = cell.row.original;
       const isDisabled = isRowSelectable ? !isRowSelectable(rowOriginal) : false;
-      const ariaLabel = (getRowAriaLabel == null ? void 0 : getRowAriaLabel(rowOriginal)) ?? "Select row";
+      const ariaLabel = (getRowAriaLabel == null ? void 0 : getRowAriaLabel(rowOriginal)) ?? "選取此列";
       const checkboxSize = size === "lg" ? "lg" : "md";
       const onCellClick = isDisabled ? void 0 : (e) => {
         e.stopPropagation();
@@ -889,9 +975,11 @@ function DataTableInner({
           // Phase 9 Issue 8 fix(2026-05-10 user 撞 + codex 重比稿 verdict ADOPT):
           // 之前 `border-r border-divider` 只 right edge → hover overlay outline:-1px 只 right
           // 邊壓 cell border,上左下 sub-pixel 不一致(user 抓「右 1px / 上左下 2px」bug)。
-          // 改 `dtCellGrid` (data-table.css:96-110)用 `box-shadow: inset` 4 邊 1px divider,
-          // 不佔 layout(per user verbatim「在 cell 內容起始位置不變」前提)→ 4 邊一致 grid line
-          // → overlay outline:-1px 4 邊都剛好壓 cell border line。
+          // 改 `dtCellGrid`(data-table.css「dtCellGrid v2/v3」段)box-shadow inset **只保右邊**
+          // `inset -1px 0 0 var(--divider)`(bottom 由 row border-b 接管、:last-child 設 none 防 2px;
+          // 2026-07-04 對齊 css 現況 — 原「4 邊 inset」敘述已被 v2/v3 取代),不佔 layout
+          // (per user verbatim「在 cell 內容起始位置不變」前提)→ 視覺 4 邊 grid line 由
+          // row border + 相鄰 cell 合成 → overlay outline:-1px 壓 cell border line。
           // Field naked edit border 仍 own(per Field SSOT)— 編輯時 Field 自帶 border 1px,
           // 跟 cell 4 邊 inset divider 視覺相疊(同 pixel)= 1 line visual,不雙線。
           inlineEdit && "dtCellGrid",
@@ -1052,6 +1140,18 @@ function DataTableInner({
     (e) => {
       var _a2;
       if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) return;
+      if (spreadsheetMode && selectedCellId == null && editingCellId == null && ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"].includes(e.key)) {
+        const allRows = table.getRowModel().rows.map((r) => r.id);
+        const allCols = table.getVisibleLeafColumns().map((c) => c.id).filter((id) => id !== SELECT_COL_ID);
+        if (allRows.length > 0 && allCols.length > 0) {
+          e.preventDefault();
+          const firstCellId = `${allRows[0]}:${allCols[0]}`;
+          setSelectedCellId(firstCellId);
+          setRangeAnchor(firstCellId);
+          setRangeFocus(null);
+        }
+        return;
+      }
       if (spreadsheetMode && selectedCellId != null && editingCellId == null) {
         const navKeys = ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Enter", "F2", "Escape"];
         if (!navKeys.includes(e.key)) return;
@@ -1114,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,
@@ -1124,7 +1227,7 @@ function DataTableInner({
       selectedCellId,
       editingCellId,
       table,
-      isCellEditable
+      canEditCell
     ]
   );
   const headerCellEl = (header, showDivider) => {
@@ -1148,7 +1251,7 @@ function DataTableInner({
               checked: headerCheckedState,
               onClick: (e) => e.stopPropagation(),
               onCheckedChange: () => toggleHeaderCheckbox(),
-              "aria-label": "Select all visible rows",
+              "aria-label": "全選可見列",
               disabled: selectableVisibleIds.length === 0
             }
           )
@@ -1199,7 +1302,8 @@ function DataTableInner({
               className: cn(
                 "flex items-center min-w-0 flex-1 gap-1 outline-none",
                 canSort && "cursor-pointer hover:text-foreground transition-colors",
-                canSort && "focus-visible:ring-2 focus-visible:ring-ring rounded-sm"
+                // 2026-07-04:rounded-sm → rounded-md(radius.spec.md 設計哲學(4)rounded-sm 保留未使用,4px 一律 rounded-md)
+                canSort && "focus-visible:ring-2 focus-visible:ring-ring rounded-md"
               ),
               children: [
                 /* @__PURE__ */ jsx(TruncateCell, { className: cn("min-w-0", align === "right" && "text-right", align === "center" && "text-center"), children: header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext()) }),
@@ -1314,6 +1418,14 @@ function DataTableInner({
     return row.getVisibleCells().filter((c) => ids.has(c.column.id));
   };
   const [dropIndicator, setDropIndicator] = React.useState(null);
+  const setDropIndicatorIfChanged = React.useCallback(
+    (next) => {
+      setDropIndicator(
+        (prev) => prev && prev.id === next.id && prev.side === next.side && prev.type === next.type ? prev : next
+      );
+    },
+    []
+  );
   const reorderableColumnIdsRef = React.useRef([]);
   const renderHeaderRow = (cols, isRight) => {
     const headers = getRegionHeaders(cols);
@@ -1379,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
@@ -1452,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,
@@ -1575,25 +1687,34 @@ function DataTableInner({
                   const nextMeta = (_a3 = nextColDef == null ? void 0 : nextColDef.columnDef) == null ? void 0 : _a3.meta;
                   if (!(nextMeta == null ? void 0 : nextMeta.type) || NON_EDIT_TYPES.includes(nextMeta.type)) continue;
                   if (!nextRow || !canEditCell(nextMeta, nextRow.original)) continue;
+                  if (editingDraft !== void 0) commitCell(rowId, colId, editingDraft);
                   setEditingCellId(cellEditId(allRows[nextRowIdx], allCols[nextColIdx]));
+                  setSelectedCellId(null);
+                  setRangeAnchor(null);
+                  setRangeFocus(null);
                   return;
                 }
               };
-              return /* @__PURE__ */ jsx("div", { onKeyDownCapture: handleEditTab, style: { width: "100%", height: "100%" }, children: /* @__PURE__ */ jsx(
-                Cell,
-                {
-                  value,
-                  meta,
-                  mode: "edit",
-                  size,
-                  autoRowHeight: false,
-                  isEditable: cellEditable,
-                  onCommit: (next) => commitCell(rowId, colId, next),
-                  onCommitLive: (next) => onCellCommit == null ? void 0 : onCellCommit(rowId, colId, next),
-                  onCancel: exitEdit,
-                  onDraft: setEditingDraft
-                }
-              ) });
+              return (
+                // 2026-07-05 D4 fix:key={cellId} 強制 per-cell remount — 相鄰同型欄位 Tab 過去時
+                // uncontrolled Input / NumberCell localValue 原封不動(上一格的字跑到下一格)。
+                // 對齊 cell-registry「mode-keyed remount canonical」(per-cell edit session 是不同 mount cycle)。
+                /* @__PURE__ */ jsx("div", { onKeyDownCapture: handleEditTab, style: { width: "100%", height: "100%" }, children: /* @__PURE__ */ jsx(
+                  Cell,
+                  {
+                    value,
+                    meta,
+                    mode: "edit",
+                    size,
+                    autoRowHeight: false,
+                    isEditable: cellEditable,
+                    onCommit: (next) => commitCell(rowId, colId, next),
+                    onCommitLive: (next) => onCellCommit == null ? void 0 : onCellCommit(rowId, colId, next),
+                    onCancel: () => cancelCellEdit(rowId, colId),
+                    onDraft: setEditingDraft
+                  }
+                ) }, cellId)
+              );
             } : void 0,
             selectedCellId: spreadsheetMode ? selectedCellId : null,
             rangeCellIds,
@@ -1729,7 +1850,7 @@ function DataTableInner({
         setDropIndicator(null);
         return;
       }
-      setDropIndicator({ id: String(over.id), side, type: "column" });
+      setDropIndicatorIfChanged({ id: String(over.id), side, type: "column" });
     } else {
       const activeIdx = allRowIds.indexOf(String(active.id));
       const overIdx = allRowIds.indexOf(String(over.id));
@@ -1742,9 +1863,9 @@ function DataTableInner({
         setDropIndicator(null);
         return;
       }
-      setDropIndicator({ id: String(over.id), side, type: "row" });
+      setDropIndicatorIfChanged({ id: String(over.id), side, type: "row" });
     }
-  }, [allRowIds, isReorderNoop]);
+  }, [allRowIds, isReorderNoop, setDropIndicatorIfChanged]);
   const handleDragCancel = React.useCallback(() => {
     setActiveDragId(null);
     setActiveDragColId(null);
@@ -1759,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]);
@@ -1818,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(
@@ -1851,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";
@@ -1865,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"],