@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

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";
@@ -11,8 +12,9 @@ import { useSensors, useSensor, PointerSensor, KeyboardSensor, pointerWithin, re
 import { cn } from "../../lib/utils.js";
 import { ICON_SIZE, ItemInlineActionButton } from "../../patterns/element-anatomy/item-anatomy.js";
 import { reconstructFullRowGhost, isReorderNoop, snapToCursorModifier, dragSourceStyle, dropIndicatorColumn, dragActiveCursor, dropIndicatorRow } from "../../lib/drag-visual.js";
-import { nakedCellEditableDisplayHover } from "../Field/field-wrapper.js";
+import { fieldDisplayTextClass, nakedCellEditableDisplayHover } from "../Field/field-wrapper.js";
 import { Tooltip, TooltipTrigger, TooltipContent } from "../Tooltip/tooltip.js";
+import { TruncatedText } from "../../patterns/element-anatomy/truncated-text.js";
 import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator } from "../DropdownMenu/dropdown-menu.js";
 import { columnTypeDefaults } from "./column-types.js";
 import { resolveCellComponent } from "./cell-registry.js";
@@ -28,6 +30,27 @@ const dataTableVariants = cva("bg-surface rounded-md overflow-hidden", {
 });
 const cellEditId = (rowId, colId) => `${rowId}__${colId}`;
 const SELECT_COL_ID = "__select__";
+function normalizeSelection(input) {
+  if (input === void 0) return void 0;
+  if (Array.isArray(input)) return { mode: "include", ids: input };
+  return input;
+}
+function applySelectIds(sel, ids, willSelect) {
+  if (sel.mode === "include") {
+    const set2 = new Set(sel.ids);
+    ids.forEach((id) => {
+      if (willSelect) set2.add(id);
+      else set2.delete(id);
+    });
+    return { mode: "include", ids: Array.from(set2) };
+  }
+  const set = new Set(sel.excluded);
+  ids.forEach((id) => {
+    if (willSelect) set.delete(id);
+    else set.add(id);
+  });
+  return { mode: "all", excluded: Array.from(set) };
+}
 const cellPadding = { paddingBlock: "var(--table-cell-py)", paddingInline: "var(--table-cell-px)" };
 const HEADER_BG = "bg-muted";
 const MIN_COLUMN_WIDTH = 80;
@@ -45,44 +68,6 @@ function columnSizeStyle(col, opts) {
 }
 const SYSTEM_COL_IDS = /* @__PURE__ */ new Set([SELECT_COL_ID, "__drag__", "__actions__"]);
 const isSystemColumn = (colId) => SYSTEM_COL_IDS.has(colId);
-let sharedResizeObserver = null;
-const roCallbacks = /* @__PURE__ */ new WeakMap();
-function getSharedRO() {
-  if (sharedResizeObserver) return sharedResizeObserver;
-  sharedResizeObserver = new ResizeObserver((entries) => {
-    entries.forEach((entry) => {
-      const cb = roCallbacks.get(entry.target);
-      if (cb) cb(entry);
-    });
-  });
-  return sharedResizeObserver;
-}
-function observeShared(el, cb) {
-  const obs = getSharedRO();
-  roCallbacks.set(el, cb);
-  obs.observe(el);
-  return () => {
-    roCallbacks.delete(el);
-    obs.unobserve(el);
-  };
-}
-function TruncateCell({ children, className }) {
-  const ref = React.useRef(null);
-  const [isTruncated, setIsTruncated] = React.useState(false);
-  React.useEffect(() => {
-    const el = ref.current;
-    if (!el) return;
-    const check = () => setIsTruncated(el.scrollWidth > el.clientWidth);
-    check();
-    return observeShared(el, check);
-  }, []);
-  const span = /* @__PURE__ */ jsx("span", { ref, className: cn("truncate min-w-0", className), children });
-  if (!isTruncated) return span;
-  return /* @__PURE__ */ jsxs(Tooltip, { children: [
-    /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: span }),
-    /* @__PURE__ */ jsx(TooltipContent, { children })
-  ] });
-}
 const SortableRowCtx = React.createContext(null);
 function SortableRowProvider(props) {
   return props.role === "primary" ? /* @__PURE__ */ jsx(SourceRowProvider, { ...props }) : /* @__PURE__ */ jsx(MirrorRowProvider, { ...props });
@@ -101,12 +86,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
@@ -119,7 +103,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({
@@ -133,7 +117,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) },
@@ -145,7 +129,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({
@@ -168,12 +152,24 @@ function DraggableHeaderCell({
   const childProps = children.props;
   const { role: _draggableRole, ...draggableAttrs } = draggable.attributes;
   const indicatorClass = dropIndicatorSide === "before" ? dropIndicatorColumn.pseudoBefore : dropIndicatorSide === "after" ? dropIndicatorColumn.pseudoAfter : "";
+  const rawListeners = draggable.listeners;
+  const guardedListeners = rawListeners ? {
+    ...rawListeners,
+    onKeyDown: (e) => {
+      var _a;
+      const target = e.target;
+      if (target !== e.currentTarget && target.closest('button, a, input, select, textarea, [role="menuitem"], [role="separator"]')) {
+        return;
+      }
+      (_a = rawListeners.onKeyDown) == null ? void 0 : _a.call(rawListeners, e);
+    }
+  } : rawListeners;
   return React.cloneElement(children, {
     ref: setRefs,
     style: { ...childProps.style ?? {}, ...dragStyle },
     "data-column-id": id,
     "data-column-locked": isLocked || void 0,
-    ...disabled ? {} : { ...draggableAttrs, ...draggable.listeners },
+    ...disabled ? {} : { ...draggableAttrs, ...guardedListeners ?? {} },
     // 2026-05-06 v14.9 cursor canonical(對齊 Notion / Jira):
     // **idle hover NOT 顯 cursor-grab** — header click 觸發 sort,grab cursor 會誤導 user 以為「點 = 拖」;
     // **drag activation 後**(isDragging=true,過 8px activationConstraint)才顯 cursor-grabbing。
@@ -199,18 +195,18 @@ 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);
     observer.observe(rowEl, { attributes: true, attributeFilter: ["data-hovered"] });
     let scrollRafId = 0;
     const onScroll = () => {
+      if (!rowEl.hasAttribute("data-hovered") && !buttonHovered && !ctx.isDragging) return;
       if (scrollRafId) cancelAnimationFrame(scrollRafId);
       scrollRafId = requestAnimationFrame(() => {
         scrollRafId = 0;
@@ -225,7 +221,7 @@ function RowDragHandle({ disabled, anyDragActive }) {
       window.removeEventListener("scroll", onScroll, true);
       window.removeEventListener("resize", onScroll);
     };
-  }, [rowEl, ctx]);
+  }, [rowEl, ctx, buttonHovered]);
   const anchor = /* @__PURE__ */ jsx(
     "span",
     {
@@ -260,11 +256,11 @@ 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,
-        pointerEvents: visible ? "auto" : "none",
-        transition: "opacity 150ms ease"
+        // 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"
       },
       className: cn(
         // 2026-05-12 debug fix(user 抓「hover 還是透明」)— Round 4.5 我未授權加
@@ -276,6 +272,7 @@ function RowDragHandle({ disabled, anyDragActive }) {
         // row 任何 state 視覺都有 token-level 對比(在 token 差異存在的 mode;light mode --surface-raised
         // 等於 --surface 是 design token semantic,非本 fix scope)。
         "bg-surface-raised hover:bg-surface-raised aria-disabled:bg-surface-raised",
+        "transition-opacity duration-150 ease-in-out motion-reduce:duration-0",
         canDrag && !showInvalid && "cursor-grab",
         canDrag && showInvalid && "cursor-not-allowed !text-error !border-error",
         // drag 進行中 source button cursor(opacity 0.5 via style;aria-disabled visual 由 Button cva 接管)
@@ -294,12 +291,48 @@ 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,
+  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(() => onEnterEdit(rowId, colId), [onEnterEdit, rowId, colId]);
+  return /* @__PURE__ */ jsx(
+    Cell,
+    {
+      value,
+      meta,
+      mode,
+      size,
+      autoRowHeight,
+      isEditable,
+      onCommit,
+      onCommitLive,
+      onCancel,
+      onRequestEdit
+    }
+  );
+});
 function DataTableInner({
   columns,
   data,
   size = "md",
   autoRowHeight = false,
-  height = "400px",
+  height: heightProp,
   overscan = 5,
   emptyState,
   enableHover = true,
@@ -334,16 +367,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);
@@ -362,14 +393,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) => {
@@ -379,18 +432,9 @@ function DataTableInner({
     },
     []
   );
-  const isCellDisabled = React.useCallback(
-    // any-allow: free-form consumer meta — same rationale as L143 renderTypedValue
-    (meta, row) => {
-      const d = meta == null ? void 0 : meta.disabled;
-      if (typeof d === "function") return d(row) === true;
-      return d === true;
-    },
-    []
-  );
   const canEditCell = React.useCallback(
-    (meta, row) => isCellEditable(meta, row) && !isCellDisabled(meta, row),
-    [isCellEditable, isCellDisabled]
+    (meta, row) => isCellEditable(meta, row),
+    [isCellEditable]
   );
   const [sorting, setSorting] = React.useState(((_a = tableOptions == null ? void 0 : tableOptions.state) == null ? void 0 : _a.sorting) ?? []);
   const [columnVisibility, setColumnVisibility] = useControllable({
@@ -401,8 +445,8 @@ function DataTableInner({
   const enabled = selectable !== false;
   const mode = selectable === "single" ? "single" : "multi";
   const [selection, setSelection] = useControllable({
-    value: selectionProp,
-    defaultValue: defaultSelection ?? [],
+    value: normalizeSelection(selectionProp),
+    defaultValue: normalizeSelection(defaultSelection) ?? { mode: "include", ids: [] },
     onChange: onSelectionChange
   });
   const anchorRowIdRef = React.useRef(null);
@@ -448,6 +492,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,
@@ -458,7 +510,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)
@@ -478,6 +533,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
@@ -491,9 +548,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]) {
@@ -501,13 +560,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);
@@ -535,6 +599,7 @@ function DataTableInner({
     isScrollingResetDelay: 250
   });
   const [bodyMaxHeight, setBodyMaxHeight] = React.useState(null);
+  const paginationBarRef = React.useRef(null);
   React.useLayoutEffect(() => {
     var _a2;
     if (!isFillHeight) {
@@ -551,7 +616,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;
@@ -631,7 +698,7 @@ function DataTableInner({
     if (rightHeaderRef.current) obs.observe(rightHeaderRef.current);
     return () => obs.disconnect();
   }, [hasLeft, hasRight, rows.length]);
-  const rowHeight = `h-table-row-${size}`;
+  const rowHeight = { sm: "h-table-row-sm", md: "h-table-row-md", lg: "h-table-row-lg" }[size] ?? "h-table-row-md";
   const enterLeaveHandlers = React.useMemo(() => {
     if (!enableHover) return { onMouseOver: void 0, onMouseOut: void 0 };
     const findRowIndex = (target) => {
@@ -671,33 +738,34 @@ function DataTableInner({
     const rowId = cell.row.id;
     const colId = cell.column.id;
     const editable = isCellEditable(meta, cell.row.original);
-    const disabled = isCellDisabled(meta, cell.row.original);
     const isEditingThisCell = editingCellId === cellEditId(rowId, colId);
     let content;
     if (colType) {
       const Cell = resolveCellComponent(colType);
-      const cellMode = experimentalActiveEditorController && isEditingThisCell ? "display" : isEditingThisCell && !disabled ? "edit" : "display";
+      const cellMode = experimentalActiveEditorController && isEditingThisCell ? "view" : isEditingThisCell ? "edit" : "view";
       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 {
       content = flexRender(cell.column.columnDef.cell, cell.getContext());
     }
     const isConsumerCompound = !colType && React.isValidElement(content);
-    return isEditingThisCell ? content : wrap ? /* @__PURE__ */ jsx("span", { className: "break-words min-w-0", children: content }) : isKnownCompound || isConsumerCompound ? content : /* @__PURE__ */ jsx(TruncateCell, { children: content });
+    return isEditingThisCell ? content : wrap ? /* @__PURE__ */ jsx("span", { className: "break-words min-w-0", children: content }) : isKnownCompound || isConsumerCompound ? content : /* @__PURE__ */ jsx(TruncatedText, { children: content });
   };
   const iconSize = ICON_SIZE[size];
   const dragDisabled = sorting.length > 0;
@@ -724,16 +792,16 @@ function DataTableInner({
   const invalidRef = React.useRef(false);
   invalidRef.current = invalidDropActive;
   const cellEl = (cell, _isLastInRow = false) => {
-    var _a2, _b2, _c2, _d, _e, _f;
+    var _a2, _b2, _c2, _d, _e, _f, _g, _h, _i;
     if (enabled && cell.column.id === SELECT_COL_ID) {
       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();
-        if (mode === "single") setSelection([rowId]);
+        if (mode === "single") setSelection({ mode: "include", ids: [rowId] });
         else toggleRow(rowId, rowOriginal, { shiftKey: e.shiftKey });
       };
       return /* @__PURE__ */ jsx(
@@ -757,7 +825,7 @@ function DataTableInner({
             Checkbox,
             {
               size: checkboxSize,
-              checked: selectionSet.has(rowId),
+              checked: isSelectedId(rowId),
               disabled: isDisabled,
               "aria-label": ariaLabel,
               onClick: (e) => {
@@ -784,11 +852,10 @@ function DataTableInner({
     const cellRowId = cell.row.id;
     const cellColId = cell.column.id;
     const cellEditable = isCellEditable(meta, cell.row.original);
-    const cellDisabled = isCellDisabled(meta, cell.row.original);
     const isEditingThisCell = editingCellId === cellEditId(cellRowId, cellColId);
     const cellSpreadsheetId = `${cellRowId}:${cellColId}`;
     const isSelectedCell = spreadsheetMode && selectedCellId === cellSpreadsheetId;
-    const onEditableCellClick = cellEditable && !cellDisabled && colType !== "boolean" && colType !== "url" && !isEditingThisCell ? (e) => {
+    const onEditableCellClick = cellEditable && colType !== "boolean" && colType !== "url" && !isEditingThisCell ? (e) => {
       if (spreadsheetMode) {
         if (e.shiftKey && rangeAnchor != null) {
           setRangeFocus(cellSpreadsheetId);
@@ -815,7 +882,12 @@ function DataTableInner({
     const canExpand = ((_b2 = (_a2 = cell.row).getCanExpand) == null ? void 0 : _b2.call(_a2)) ?? false;
     const isExpanded = ((_d = (_c2 = cell.row).getIsExpanded) == null ? void 0 : _d.call(_c2)) ?? false;
     const toggleExpand = (_f = (_e = cell.row).getToggleExpandedHandler) == null ? void 0 : _f.call(_e);
-    const showNestedPrefix = isFirstContent && (depth > 0 || canExpand);
+    const siblingRows = ((_i = (_h = (_g = cell.row).getParentRow) == null ? void 0 : _h.call(_g)) == null ? void 0 : _i.subRows) ?? table.getCoreRowModel().rows;
+    const siblingHasExpand = isFirstContent && siblingRows.some((r) => {
+      var _a3;
+      return ((_a3 = r.getCanExpand) == null ? void 0 : _a3.call(r)) ?? false;
+    });
+    const showNestedPrefix = isFirstContent && (depth > 0 || canExpand || siblingHasExpand);
     const rawCellError = cellErrors == null ? void 0 : cellErrors[`${cellRowId}:${cellColId}`];
     const cellErrorMessages = (() => {
       if (isEditingThisCell) return null;
@@ -837,7 +909,6 @@ function DataTableInner({
         "data-column-id": cell.column.id,
         "data-cell-id": `${cell.row.id}:${cell.column.id}`,
         "data-range-cell": spreadsheetMode && rangeCellIdSet.has(`${cell.row.id}:${cell.column.id}`) ? "" : void 0,
-        "data-cell-disabled": cellDisabled ? "true" : void 0,
         "aria-describedby": cellErrorId,
         "aria-invalid": hasCellError || void 0,
         className: cn(
@@ -851,7 +922,11 @@ function DataTableInner({
           //     「框框跟 cell 一樣大並取代 cell 的框且與 table 隔線無縫接軌」(2026-05-05)。
           //   - **沒有** cell 自己 box-shadow ring — focus / hover / open ring 由 Field naked 自帶
           //     state machine 提供(對齊 user「狀態樣式取決於原輸入框」reminder)
-          "group/cell flex text-foreground text-body font-normal shrink-0 relative self-stretch",
+          // 字級隨 size:sm/md text-body / lg text-body-lg(fieldDisplayTextClass),對齊 Field family
+          // size→font SSOT。此為非-Field content(consumer 自訂 cell / TruncatedText 純文字)的 fallback 字級;
+          // typed cell 各自的 Field 控件已自帶 size→font(cell-registry 傳 size)。
+          "group/cell flex text-foreground font-normal shrink-0 relative self-stretch",
+          fieldDisplayTextClass(size),
           // Issue 9(2026-05-10):有 cell error → unset overflow-hidden 讓 error message
           // wrap 撐 row 高。**H1(2026-05-10)升級**:overflow-visible 條件改 `rowHasAnyError` —
           // row 內任一 cell 有 error 整 row 全 cells 都 overflow-visible(error 訊息可能多行
@@ -863,23 +938,25 @@ 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",
           onEditableCellClick && ["cursor-pointer", nakedCellEditableDisplayHover],
-          // editable cell display hover affordance(對齊 Notion / Airtable hover-cell-shows-border canonical)
-          // 2026-05-13 Q3 cell disabled SSOT(per codex Q3 verdict + user 拍板「全部馬不停蹄做完」):
-          // bg `--bg-disabled` component-state token(color.spec.md:671 owner)+ cursor 抑制 click affordance。
-          cellDisabled && "bg-disabled cursor-not-allowed",
+          // editable cell view hover affordance(對齊 Notion / Airtable hover-cell-shows-border canonical)
+          // a11y(2026-07-14 dim-10 修):非 spreadsheet inlineEdit cell 可 Tab 聚焦(見下方
+          // tabIndex/onKeyDown)— focus-visible ring 對齊本檔 expand button / sortable header canonical。
+          onEditableCellClick && !spreadsheetMode && "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
           // z-10 raise inline-edit cell;portal mode 不需(layer z-3 already on top)。
           isEditingThisCell && !experimentalActiveEditorController && "z-10"
         ),
         style: {
           ...columnSizeStyle(cell.column, { resize: enableColumnResize, isSystemCol: isSystemColumn(cell.column.id) }),
-          // Padding override 只在 inline-edit cell(naked Field 撐滿 cell);portal mode cell 走正常 display padding
+          // Padding override 只在 inline-edit cell(naked Field 撐滿 cell);portal mode cell 走正常 view padding
           ...isEditingThisCell && !experimentalActiveEditorController ? {} : cellPadding,
           // Slice D Step 2(2026-05-10):flag 開時 set CSS variable 抑制 Field naked hover outline,
           // 讓 overlay layer 接管 hover ring paint(per RFC Contract 8 「one geometry owner, two paint owners」)。
@@ -887,6 +964,14 @@ function DataTableInner({
           ...experimentalSpreadsheetOverlay && { "--cell-hover-outline-color": "transparent" }
         },
         onClick: onEditableCellClick,
+        tabIndex: onEditableCellClick && !spreadsheetMode ? 0 : void 0,
+        onKeyDown: onEditableCellClick && !spreadsheetMode ? (e) => {
+          if (e.target !== e.currentTarget) return;
+          if (e.key === "Enter" || e.key === "F2") {
+            e.preventDefault();
+            setEditingCellId(cellEditId(cellRowId, cellColId));
+          }
+        } : void 0,
         children: hasCellError ? /* @__PURE__ */ jsxs("span", { className: "flex flex-col self-stretch w-full min-w-0 gap-1", children: [
           /* @__PURE__ */ jsxs("span", { className: "flex flex-1 min-w-0", children: [
             showNestedPrefix && /* @__PURE__ */ jsx(
@@ -900,7 +985,7 @@ function DataTableInner({
                     type: "button",
                     "aria-label": isExpanded ? "收合" : "展開",
                     "aria-expanded": isExpanded,
-                    className: "inline-flex items-center justify-center shrink-0 w-4 h-4 mr-2 text-fg-muted hover:text-foreground rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-transform",
+                    className: "inline-flex items-center justify-center shrink-0 w-4 h-4 mr-2 text-fg-muted hover:text-fg-secondary rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-transform motion-reduce:duration-0",
                     style: { transform: isExpanded ? "rotate(90deg)" : void 0 },
                     onClick: (e) => {
                       e.stopPropagation();
@@ -933,7 +1018,7 @@ function DataTableInner({
                   type: "button",
                   "aria-label": isExpanded ? "收合" : "展開",
                   "aria-expanded": isExpanded,
-                  className: "inline-flex items-center justify-center shrink-0 w-4 h-4 mr-2 text-fg-muted hover:text-foreground rounded-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-transform",
+                  className: "inline-flex items-center justify-center shrink-0 w-4 h-4 mr-2 text-fg-muted hover:text-fg-secondary rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring transition-transform motion-reduce:duration-0",
                   style: { transform: isExpanded ? "rotate(90deg)" : void 0 },
                   onClick: (e) => {
                     e.stopPropagation();
@@ -963,33 +1048,42 @@ function DataTableInner({
   React.useEffect(() => {
     if (!enabled || preserveSelectionOnFilter) return;
     setSelection((prev) => {
-      const filtered = prev.filter((id) => visibleRowIdsSet.has(id));
-      return filtered.length === prev.length ? prev : filtered;
+      if (prev.mode === "all") return prev;
+      const filtered = prev.ids.filter((id) => visibleRowIdsSet.has(id));
+      return filtered.length === prev.ids.length ? prev : { mode: "include", ids: filtered };
     });
   }, [visibleRowIdsKey, enabled, preserveSelectionOnFilter, visibleRowIdsSet, setSelection]);
   const selectableVisibleIds = React.useMemo(() => {
     if (!enabled) return [];
     return rows.filter((r) => !isRowSelectable || isRowSelectable(r.original)).map((r) => r.id);
   }, [rows, enabled, isRowSelectable]);
-  const selectionSet = React.useMemo(() => new Set(selection), [selection]);
-  const visibleSelectedCount = selectableVisibleIds.filter((id) => selectionSet.has(id)).length;
+  const includeSet = React.useMemo(
+    () => selection.mode === "include" ? new Set(selection.ids) : /* @__PURE__ */ new Set(),
+    [selection]
+  );
+  const excludeSet = React.useMemo(
+    () => selection.mode === "all" ? new Set(selection.excluded) : /* @__PURE__ */ new Set(),
+    [selection]
+  );
+  const isSelectedId = React.useCallback(
+    (id) => selection.mode === "include" ? includeSet.has(id) : !excludeSet.has(id),
+    [selection.mode, includeSet, excludeSet]
+  );
+  const hasAnySelection = selection.mode === "all" || includeSet.size > 0;
+  const visibleSelectedCount = selectableVisibleIds.filter((id) => isSelectedId(id)).length;
   const headerCheckedState = selectableVisibleIds.length === 0 ? false : visibleSelectedCount === 0 ? false : visibleSelectedCount === selectableVisibleIds.length ? true : "indeterminate";
   const visibleIdToRow = React.useMemo(
     () => new Map(rows.map((r) => [r.id, r])),
     [rows]
   );
   const toggleHeaderCheckbox = React.useCallback(() => {
-    if (headerCheckedState === true) {
-      const visibleSet = new Set(selectableVisibleIds);
-      setSelection((prev) => prev.filter((id) => !visibleSet.has(id)));
-    } else {
-      setSelection((prev) => Array.from(/* @__PURE__ */ new Set([...prev, ...selectableVisibleIds])));
-    }
+    const willSelect = headerCheckedState !== true;
+    setSelection((prev) => applySelectIds(prev, selectableVisibleIds, willSelect));
   }, [headerCheckedState, selectableVisibleIds, setSelection]);
   const toggleRow = React.useCallback((rowId, rowOriginal, opts) => {
     if (isRowSelectable && !isRowSelectable(rowOriginal)) return;
     if (mode === "single") {
-      setSelection(selectionSet.has(rowId) ? [] : [rowId]);
+      setSelection(isSelectedId(rowId) ? { mode: "include", ids: [] } : { mode: "include", ids: [rowId] });
       anchorRowIdRef.current = rowId;
       return;
     }
@@ -1004,28 +1098,37 @@ function DataTableInner({
           const row = visibleIdToRow.get(id);
           return row && (!isRowSelectable || isRowSelectable(row.original));
         });
-        const willCheck = !selectionSet.has(rowId);
-        setSelection((prev) => {
-          const set = new Set(prev);
-          rangeIds.forEach((id) => willCheck ? set.add(id) : set.delete(id));
-          return Array.from(set);
-        });
+        const willCheck2 = !isSelectedId(rowId);
+        setSelection((prev) => applySelectIds(prev, rangeIds, willCheck2));
         return;
       }
     }
-    setSelection((prev) => {
-      const set = new Set(prev);
-      if (set.has(rowId)) set.delete(rowId);
-      else set.add(rowId);
-      return Array.from(set);
-    });
+    const willCheck = !isSelectedId(rowId);
+    setSelection((prev) => applySelectIds(prev, [rowId], willCheck));
     anchorRowIdRef.current = rowId;
-  }, [isRowSelectable, mode, selectionSet, rows, visibleIdToRow, setSelection]);
+  }, [isRowSelectable, mode, isSelectedId, rows, visibleIdToRow, setSelection]);
   const tableKeyboardHandler = React.useCallback(
     (e) => {
-      var _a2;
+      var _a2, _b2;
       if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) return;
-      if (spreadsheetMode && selectedCellId != null && editingCellId == null) {
+      const spreadsheetKbTarget = e.target;
+      const targetIsEmbeddedControl = !!((_a2 = spreadsheetKbTarget == null ? void 0 : spreadsheetKbTarget.closest) == null ? void 0 : _a2.call(
+        spreadsheetKbTarget,
+        'button, a[href], input, select, textarea, [contenteditable="true"]'
+      ));
+      if (spreadsheetMode && !targetIsEmbeddedControl && 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 && !targetIsEmbeddedControl && selectedCellId != null && editingCellId == null) {
         const navKeys = ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Enter", "F2", "Escape"];
         if (!navKeys.includes(e.key)) return;
         const lastColon = selectedCellId.lastIndexOf(":");
@@ -1049,7 +1152,7 @@ function DataTableInner({
         } else if (e.key === "Enter" || e.key === "F2") {
           const row = table.getRowModel().rowsById[curRowId];
           const colDef = table.getAllLeafColumns().find((c) => c.id === curColId);
-          const meta = (_a2 = colDef == null ? void 0 : colDef.columnDef) == null ? void 0 : _a2.meta;
+          const meta = (_b2 = colDef == null ? void 0 : colDef.columnDef) == null ? void 0 : _b2.meta;
           if ((meta == null ? void 0 : meta.type) && meta.type !== "boolean" && meta.type !== "url" && row && canEditCell(meta, row.original)) {
             e.preventDefault();
             setEditingCellId(cellEditId(curRowId, curColId));
@@ -1075,29 +1178,34 @@ function DataTableInner({
         return;
       }
       if (!enabled) return;
+      const kbTarget = e.target;
+      if (editingCellId != null || kbTarget && (kbTarget.tagName === "INPUT" || kbTarget.tagName === "TEXTAREA" || kbTarget.tagName === "SELECT" || kbTarget.isContentEditable)) return;
       if ((e.metaKey || e.ctrlKey) && e.key === "a" && mode === "multi") {
         e.preventDefault();
-        setSelection((prev) => Array.from(/* @__PURE__ */ new Set([...prev, ...selectableVisibleIds])));
+        setSelection((prev) => applySelectIds(prev, selectableVisibleIds, true));
         return;
       }
-      if (e.key === "Escape" && selection.length > 0) {
+      if (e.key === "Escape" && hasAnySelection) {
         e.preventDefault();
-        setSelection([]);
+        setSelection({ mode: "include", ids: [] });
         anchorRowIdRef.current = null;
         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)。
     [
       enabled,
       mode,
-      selection.length,
+      hasAnySelection,
       selectableVisibleIds,
       setSelection,
       spreadsheetMode,
       selectedCellId,
       editingCellId,
       table,
-      isCellEditable
+      canEditCell
     ]
   );
   const headerCellEl = (header, showDivider) => {
@@ -1121,7 +1229,7 @@ function DataTableInner({
               checked: headerCheckedState,
               onClick: (e) => e.stopPropagation(),
               onCheckedChange: () => toggleHeaderCheckbox(),
-              "aria-label": "Select all visible rows",
+              "aria-label": "全選可見列",
               disabled: selectableVisibleIds.length === 0
             }
           )
@@ -1148,7 +1256,10 @@ function DataTableInner({
           // absolute → hover 顯時佔位 → label 自動讓出空間給 sort + more,**不再重疊**(對齊
           // user 圖示質疑 + Notion / Airtable header layout 共識)。
           // cell padding 12px 由外層 cellPadding style 提供 → more 距 cell 右邊 = 12px。
-          "group relative flex items-center gap-2 text-fg-secondary text-body font-normal shrink-0 overflow-hidden select-none",
+          // header 字級也隨 size(原寫死 text-body → lg 表格 header 字偏小,跟 body 不一致)。
+          // 對齊 cell wrapper + Field family size→font SSOT。色弱化由 text-fg-secondary 維持。
+          "group relative flex items-center gap-2 text-fg-secondary font-normal shrink-0 overflow-hidden select-none",
+          fieldDisplayTextClass(size),
           align === "right" && "justify-end",
           align === "center" && "justify-center"
         ),
@@ -1169,14 +1280,19 @@ 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()) }),
+                /* @__PURE__ */ jsx(TruncatedText, { className: cn("min-w-0", align === "right" && "text-right", align === "center" && "text-center"), children: header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext()) }),
                 canSort && sortDir && !isMultiSort && // 2026-05-18 改 per user 拍板「DataTable sort 跟 row size 變」+「做完」approval:
                 // 原固定 14 違反 uiSize.spec.md Icon Tier(sm/md→16, lg→20)。改 ICON_SIZE[size]
                 // 隨 DataTable size prop 變。
-                /* @__PURE__ */ jsx(SortIcon, { size: ICON_SIZE[size], "aria-hidden": true, className: "shrink-0 text-fg-secondary" })
+                // 顏色不釘死(2026-08-18 user 拍板「與 label 同色連動」):繼承點擊區文字色 —
+                // 靜止 fg-secondary、hover 隨父層 hover:text-foreground 與 label 同升。禁 fg-muted
+                //(muted 家 = 永遠在場的裝飾/affordance 標記;排序箭頭 = 套用後才出現的狀態資訊)、
+                // 禁 primary。SSOT → data-table.spec.md「Header cell internal」表 sort arrow 顏色列。
+                /* @__PURE__ */ jsx(SortIcon, { size: ICON_SIZE[size], "aria-hidden": true, className: "shrink-0" })
               ]
             }
           ),
@@ -1230,16 +1346,34 @@ function DataTableInner({
             const colOptIn = (colMeta == null ? void 0 : colMeta.resizable) !== false;
             const isResizable = enableColumnResize && !isSystemColumn(colId) && colOptIn;
             const isResizing = (_b2 = (_a3 = header.column).getIsResizing) == null ? void 0 : _b2.call(_a3);
+            const effectiveMinWidth = header.column.columnDef.minSize ?? MIN_COLUMN_WIDTH;
+            const currentWidth = Math.round(header.column.getSize());
+            const RESIZE_KEY_STEP = 16;
             if (!showDivider && !isResizable) return null;
             return /* @__PURE__ */ jsx(
               "span",
               {
                 role: isResizable ? "separator" : void 0,
                 "aria-orientation": isResizable ? "vertical" : void 0,
-                "aria-label": isResizable ? "拖曳調整欄寬" : void 0,
+                "aria-label": isResizable ? "調整欄寬" : void 0,
+                tabIndex: isResizable ? 0 : void 0,
+                "aria-valuenow": isResizable ? currentWidth : void 0,
+                "aria-valuemin": isResizable ? effectiveMinWidth : void 0,
+                "aria-valuetext": isResizable ? `${currentWidth}px` : void 0,
+                onKeyDown: isResizable ? (e) => {
+                  let next = null;
+                  if (e.key === "ArrowLeft") next = Math.max(effectiveMinWidth, currentWidth - RESIZE_KEY_STEP);
+                  else if (e.key === "ArrowRight") next = currentWidth + RESIZE_KEY_STEP;
+                  else if (e.key === "Home") next = effectiveMinWidth;
+                  if (next == null) return;
+                  e.preventDefault();
+                  e.stopPropagation();
+                  table.setColumnSizing((prev) => ({ ...prev, [colId]: next }));
+                } : void 0,
                 className: cn(
                   "group/resize absolute top-0 bottom-0 right-0 -mr-[3px] w-[7px]",
-                  isResizable && "cursor-col-resize select-none"
+                  isResizable && "cursor-col-resize select-none",
+                  isResizable && "focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring"
                 ),
                 onPointerDownCapture: isResizable ? (e) => {
                   var _a4;
@@ -1284,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);
@@ -1325,7 +1467,7 @@ function DataTableInner({
     const rowEl = (row, idx, opts) => {
       const showBorder = bordered !== false ? !(opts == null ? void 0 : opts.isLast) : true;
       const isThisRowDragging = enableRowDrag && activeDragId === row.id;
-      const useSortableWrap = enableRowDrag;
+      const dragRowWrap = enableRowDrag;
       const rowHasError = !!cellErrors && row.getVisibleCells().some((c) => {
         const key = `${row.id}:${c.column.id}`;
         const v = cellErrors[key];
@@ -1349,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
@@ -1385,16 +1527,16 @@ function DataTableInner({
         },
         row.id
       );
-      if (useSortableWrap) {
+      if (dragRowWrap) {
         const rowInvalidDrop = isThisRowDragging && invalidDropActive;
         return /* @__PURE__ */ jsx(SortableRowProvider, { id: row.id, disabled: dragDisabled, role: regionRole, invalidDrop: rowInvalidDrop, children: (ctx) => baseRowDiv({
-          // mirror 也掛 setNodeRef — dnd-kit 內部以 hook instance 為單元,
-          // 多 instance 同 id 時,measurement 走最後 mount 的;不影響 transform 一致性
+          // primary 掛 useDraggable+useDroppable 合成 ref;mirror 只掛 useDroppable ref
+          // (v15.4 split — mirror 不進 drag source store,isDragging 走 useDndContext 同步)
           ref: ctx.setNodeRef,
           style: ctx.style,
           isDragging: ctx.isDragging,
-          // v15.2 整列可拖:listeners + attributes spread 在 row div 上(只 primary,
-          // mirror region 沒 listeners 避免 a11y 重複 announce / pointer 雙觸發)
+          // v15.6 button-only:rowListeners 恆 undefined(activator = RowDragHandle Button),
+          // baseRowDiv spread `{...(extra?.listeners ?? {})}` 自動 noop;attributes 留空 = row 純 container
           listeners: ctx.rowListeners,
           attributes: ctx.rowAttributes
         }) }, row.id);
@@ -1422,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,
@@ -1463,7 +1605,10 @@ function DataTableInner({
               ref: centerBodyRef,
               "data-datatable-hscroll": true,
               "data-datatable-panel": "center",
-              className: "flex-1 min-w-0 overflow-x-auto overflow-y-auto",
+              role: isEmpty ? void 0 : "rowgroup",
+              tabIndex: enabled || spreadsheetMode || isEmpty ? void 0 : 0,
+              "aria-label": enabled || spreadsheetMode || isEmpty ? void 0 : "表格內容,可捲動",
+              className: "flex-1 min-w-0 overflow-x-auto overflow-y-auto focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring",
               style: isFillHeight && bodyMaxHeight != null ? { maxHeight: bodyMaxHeight } : hasHeightConstraint ? { maxHeight: height } : void 0,
               onScroll: onCenterBodyScroll,
               children: /* @__PURE__ */ jsx("div", { style: { minWidth: centerColsWidth }, children: renderBodyRows(centerCols, true, false) })
@@ -1545,28 +1690,36 @@ 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,
             cellClickEntersEdit: (cellId) => {
               var _a2;
               const lastColonIdx = cellId.lastIndexOf(":");
@@ -1699,7 +1852,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));
@@ -1712,9 +1865,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);
@@ -1729,7 +1882,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]);
@@ -1788,6 +1941,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(
@@ -1819,13 +1999,13 @@ function DataTableInner({
     return /* @__PURE__ */ jsx(
       RadioGroupPrimitive.Root,
       {
-        value: selection[0] ?? "",
-        onValueChange: (v) => v && setSelection([v]),
-        children: wrapWithDnd(tableContent)
+        value: selection.mode === "include" ? selection.ids[0] ?? "" : "",
+        onValueChange: (v) => v && setSelection({ mode: "include", ids: [v] }),
+        children: wrapWithDnd(composedContent)
       }
     );
   }
-  return wrapWithDnd(tableContent);
+  return wrapWithDnd(composedContent);
 }
 const DataTable = React.forwardRef(DataTableInner);
 DataTable.displayName = "DataTable";
@@ -1835,7 +2015,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"],