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

package/src/components/DataTable/data-table.tsx

@@ -1,13 +1,32 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 // code-quality-allow: file-size — foundational composite — 拆檔會複雜化 context / ref / state 同步
+//
+// ── 檔案結構(2026-05-03 split matrix;2026-06-11 自 data-table.spec.md 遷入,Level 4 code home)──
+// 每個檔過 M21 / M17 / Rule-of-3 三 test:
+//   - data-table.tsx(主,foundational)
+//   - data-table-filter-panel.tsx + data-table-sort-manager.tsx + data-table-column-visibility-panel.tsx(panel state 隔離)
+//   - data-table-filter-group.tsx + data-table-filter-value-picker.tsx(@internal;2026-07-14 filter panel
+//     過 800 hard cap 拆檔 — row/nested-group renderer + ValueShape picker,只被 panel 消費)
+//   - cell-registry.tsx(column type → cell view / edit 解析 SSOT)
+//   - data-table-interaction-layer.tsx + active-editor-controller.ts(spreadsheet overlay + portal editor)
+//   - column-types.ts + filter-operators.ts(✓ Rule-of-3 SSOT,3+ consumer)
+//   - filter-tree.ts(pure data + eval,test isolation)
+//   - lib/column-meta.ts(Internal SSOT,消 5 處 `(col as any)`)
+//   - + stories / spec / css
+// M21 retract:filter-value-picker.tsx 1 consumer → 2026-05-03 inline 回 panel(上列 2026-07-14
+//   @internal 拆檔非 M21 迴轉:非 public 抽象,file-size hard cap 驅動,consumer 仍只見 panel)。
 import * as React from 'react'
 import { createPortal } from 'react-dom'
 import { Empty } from '@/design-system/components/Empty/empty'
+// L5 分頁(2026-07-06):Pagination = 分頁完整功能 SSOT(頁碼 + showTotal + 每頁筆數選單
+// 全 own 在 Pagination;共用模式,Ant Table 消費 Pagination 同派)—— DataTable 只轉發 config
+import { Pagination } from '@/design-system/components/Pagination/pagination'
 import {
   useReactTable,
   getCoreRowModel,
   getSortedRowModel,
   getExpandedRowModel,
+  getPaginationRowModel,
   flexRender,
   type ColumnDef,
   type SortingState,
@@ -24,12 +43,13 @@ import { DndContext, DragOverlay, useDraggable, useDroppable, useDndContext, poi
 import { cn } from '@/lib/utils'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 import { dragSourceStyle, dropIndicatorRow, dropIndicatorColumn, dragActiveCursor, isReorderNoop, reconstructFullRowGhost, snapToCursorModifier } from '@/design-system/lib/drag-visual'
-import { nakedCellEditableDisplayHover } from '@/design-system/components/Field/field-wrapper'
+import { nakedCellEditableDisplayHover, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
+import { TruncatedText } from '@/design-system/patterns/element-anatomy/truncated-text'
 import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator } from '@/design-system/components/DropdownMenu/dropdown-menu'
 import { ItemInlineActionButton } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { columnTypeDefaults, type ColumnType } from './column-types'
-import { resolveCellComponent } from './cell-registry'
+import { resolveCellComponent, type CellComponentProps } from './cell-registry'
 import { DataTableInteractionLayer } from './data-table-interaction-layer'
 import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
 import { RadioGroupItem } from '@/design-system/components/RadioGroup/radio-group'
@@ -56,10 +76,17 @@ type TableSize = 'sm' | 'md' | 'lg'
 export interface DataTableProps<TData>
   extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,
     VariantProps<typeof dataTableVariants> {
+  // any-allow: TanStack ColumnDef TValue idiom(per-column value 型別異質,官方範例同)— 對齊本 module 既有 escape 紀律
   columns: ColumnDef<TData, any>[]
   data: TData[]
   size?: TableSize
   autoRowHeight?: boolean
+  /**
+   * 容器高度。預設 '400px'(body 內捲動);'auto' = 自然高度(hug rows);'100%' = fill parent。
+   * L5 分頁(2026-07-06):啟用 `pagination` 且未顯式傳 height 時預設改 'auto' —— 分頁的
+   * 導覽通道是頁碼,再疊 body 內捲動 = 雙重導覽(一頁 20 筆只露 10 筆);對齊 Ant Table
+   * 無預設高度罩、`scroll.y` 顯式選配的慣例。顯式傳 height 照舊尊重(分頁 + 頁內捲動可並用)。
+   */
   height?: string
   overscan?: number
   emptyState?: React.ReactNode
@@ -70,7 +97,7 @@ export interface DataTableProps<TData>
   /**
    * Issue 9 cell error system(2026-05-10)。
    *
-   * Map of `${rowId}:${colId}` → error message(string | string[])。Cell display mode 在 content
+   * Map of `${rowId}:${colId}` → error message(string | string[])。Cell view mode 在 content
    * 下方渲 `text-body text-error` 訊息,gap-1 spacing。Multi-error 用 array → ul / li 分行渲。
    *
    * **使用建議**:
@@ -92,7 +119,8 @@ export interface DataTableProps<TData>
    * Slice D Step 1B(2026-05-10):啟用 spreadsheet-grade interaction overlay。
    * Default false(backward-compat)。Enable 後 hover/editor/selected/range 由
    * `DataTableInteractionLayer` overlay 統一畫,per `.claude/planning/datatable-spreadsheet-rfc.md`。
-   * 漸進切換階段,當前 v1 minimal:hover overlay 1 layer。
+   * 現況:hover ring + selection ring + active editor host 三個 sub-layer
+   * (詳 `data-table-interaction-layer.tsx` 檔頭)。
    */
   experimentalSpreadsheetOverlay?: boolean
   /**
@@ -108,32 +136,33 @@ export interface DataTableProps<TData>
    * Slice D Step 4(spreadsheet semantics,2026-05-10 user 拍板 + codex Layer B Q2.1 confirm):
    * Excel-like cell selection:click 1=select / click 2=edit / Shift+click=range。
    * Default false opt-in(per codex「DataTable is not a spreadsheet」既有原則 +
-   * data-table.principles.stories.tsx L283-292)。
+   * data-table.principles.stories.tsx「不是試算表」principle story)。
    * Enable 後 inlineEdit cell click 行為:
    *   - Plain click → setSelectedCellId,**不**進 edit mode
    *   - Click on already-selected → enter edit
    *   - Shift+click → extend range from anchor
    *   - Double-click / Enter / F2 / printable(deferred) → enter edit on selected
    *   - Click empty area → clear selection
-   * 視覺:Layer 渲 SelectionRect(solid `--primary` 2px border)+ RangeRect
-   *   (`--primary-subtle` bg fill)— per user「不要 dash 直接實的就好」+ codex Q2.2 token。
+   * 視覺:selection ring 1px `--primary`(layer `CELL_RING_STYLES.selected`);range 視覺
+   *   = cell-bg `--primary-subtle`(`[data-range-cell]` CSS),outer ring 已 2026-05-10 retire
+   *   — per user「不要 dash 直接實的就好」+ codex Q2.2 token。
    */
   spreadsheetMode?: boolean
 
   // ── L2 Selection(see data-table.spec.md「L2 選取」)──
-  /** 已選 row IDs(controlled) */
-  selection?: string[]
-  /** 預設選取(uncontrolled) */
-  defaultSelection?: string[]
-  /** Selection 變更 callback */
-  onSelectionChange?: (next: string[]) => void
+  /** 已選列(controlled)。傳 string[] = include shorthand;傳 DataTableSelection 支援反向選取(all + excluded) */
+  selection?: string[] | DataTableSelection
+  /** 預設選取(uncontrolled);同上接受 string[] 或 DataTableSelection */
+  defaultSelection?: string[] | DataTableSelection
+  /** Selection 變更 callback(emit DataTableSelection union;include / all 兩模型) */
+  onSelectionChange?: (next: DataTableSelection) => void
   /** 是否啟用 selection / 模式;true 等同 'multi' */
   selectable?: boolean | 'single' | 'multi'
   /** Row 是否可選(disabled rows 只 disable checkbox,row 內容正常 render) */
   isRowSelectable?: (row: TData) => boolean
   /** 取 row 唯一 ID(selection 用);default `(row, index) => String(index)` */
   getRowId?: (row: TData, index: number) => string
-  /** Checkbox aria-label fallback;default `'Select row'` */
+  /** Checkbox aria-label fallback;default `'選取此列'` */
   getRowAriaLabel?: (row: TData) => string
   /** Filter 後 hidden selected rows 是否保留(default false,對齊 Material/AG Grid 共識) */
   preserveSelectionOnFilter?: boolean
@@ -175,8 +204,8 @@ export interface DataTableProps<TData>
    *
    * **v2(2026-05-05)修正**:
    * - Virtualizer × transform:被拖 row 略過 `measureElement`(透過 SortableRowCtx 廣播 active id),避免 transform 干擾測量
-   * - 3-panel mirror sync:每 region 都呼叫 `useSortable({id})`(同 SortableContext 共用 state),mirror 自然取得相同 transform
-   * - Cross-parent drop:nested 全 row 進 SortableContext.items,自訂 collisionDetection 過濾出「同 parent siblings」;cross-parent over → 不觸發,handle cursor `not-allowed`
+   * - 3-panel mirror sync:primary region 呼叫 `useDraggable` + `useDroppable`;mirror region 只 `useDroppable`(v15.4 split),isDragging 由 `useDndContext` active.id 同步 → 三 region 視覺一致
+   * - Cross-parent drop:nested 全 row 各自 `useDroppable`,自訂 collisionDetection 過濾出「同 parent siblings」;cross-parent over → 不觸發,handle cursor `not-allowed`
    *
    * 詳 `data-table.spec.md`「L4 Row drag」段。
    */
@@ -222,19 +251,42 @@ export interface DataTableProps<TData>
    * @param position 'before' | 'after'
    */
   onColumnReorder?: (sourceId: string, targetId: string, position: 'before' | 'after') => void
+  /**
+   * L5 分頁(2026-07-06):`true` 或 config 物件啟用——內部接 TanStack `getPaginationRowModel`,
+   * 表格下方渲染分頁列(消費 `<Pagination>` 獨立元件,間距 tight、頁碼靠右)。
+   * 啟用時虛擬滾動自動關閉(TanStack 官方:互斥替代策略)。v1 = client-side only。
+   * 詳 data-table.spec.md「L5:分頁」段。
+   */
+  pagination?: boolean | DataTablePaginationOptions
+}
+
+/** L5 分頁 config(頁碼 1-based 對外,對齊 Pagination / Ant;詳 data-table.spec.md「L5:分頁」段) */
+export interface DataTablePaginationOptions {
+  /** 每頁筆數(預設 20) */
+  pageSize?: number
+  /** 每頁筆數選項;傳了才渲染「每頁 N 筆」Select(消費既有 Select size="sm") */
+  pageSizeOptions?: number[]
+  /** 左側「共 N 筆」文字(opt-in,= Ant showTotal 邏輯;數源 = filter 後全集 getPrePaginationRowModel,非 selection all-mode 的 server-side 全集數 M — 那是 consumer 自持) */
+  showTotal?: boolean
+  /** 當前頁(1-based,controlled;不傳 = uncontrolled) */
+  page?: number
+  /** uncontrolled 初始頁(1-based,預設 1) */
+  defaultPage?: number
+  onPageChange?: (page: number) => void
+  onPageSizeChange?: (pageSize: number) => void
 }
 
 // ── Cell Rendering(Phase C 2026-05-05 — type-keyed registry SSOT)─────────────
 //
 // 原 `renderTypedValue` switch + `EditableCellContent` switch 兩條平行 type-switch
 // 已 collapse 為單一 `cellRegistry`(./cell-registry.ts)— 每個 type → 一個 cell component,
-// 同時處理 display + edit mode(底層 Field control 的 mode prop)。對齊 M17 SSOT consolidation。
+// 同時處理 view + edit mode(底層 Field control 的 mode prop)。對齊 M17 SSOT consolidation。
 //
 // 對齊 Notion / Airtable type-aware inline edit canonical(詳 spec §十二):
 //   - string / number / currency:cell click → inline edit
 //   - date / time / select / multiSelect / person / multiPerson:cell click → 進 edit mode
 //   - boolean:不分 read/edit mode,直接 `<Checkbox>` 點即 toggle + commit
-//   - url:read = LinkInput display + hover Pencil button,click Pencil 才進 edit mode
+//   - url:read = LinkInput view + hover Pencil button,click Pencil 才進 edit mode
 //
 // Cell id format: `${rowId}__${columnId}`(編輯狀態 keying)
 // Commit: blur OR Enter OR overlay close → 呼叫 onCellCommit
@@ -251,6 +303,50 @@ const cellEditId = (rowId: string, colId: string) => `${rowId}__${colId}`
 //   (詳 ./data-table.css)— consumer 可走 CSS override 改值,不再 hard-code in TS。
 // L2 selection 內部 column id(避免 magic string 重複)
 const SELECT_COL_ID = '__select__'
+
+/**
+ * L2 選取模型(discriminated union,2026-06-22 對齊 MUI X DataGrid v8
+ * rowSelectionModel { type: include | exclude, ids } + AG Grid selectAll + toggledNodes)。
+ *
+ * - mode==='include' (ids):只選 ids 列(預設;= 載入/可見列逐一選取)。
+ * - mode==='all' (excluded):全資料集(filter 後)選取,扣掉 excluded —— 反向選取(inverted)。
+ *   解決「全選 10k 筆只載 50 筆 → 無法列舉其餘 ID」:all 模式「選取 = 全集 − excluded」,
+ *   任何 toggle 都只是 excluded 的 add/remove,對任意順序封閉、O(1)、不需列舉未載入 ID。
+ *
+ * 計數(consumer):mode==='all' ? M − excluded.length : ids.length(M = consumer 自持的
+ * server-side / filter 後全集筆數;2026-07-13 D1 拍板:DataTable 不收 totalCount prop — DS 內部
+ * 零消費 no-op 已移除,計數本來就全由 consumer 端算)。
+ * 進入 all 模式:consumer 在「選取全部 M」hint 點擊時 setSelection({ mode: 'all', excluded: [] })。
+ */
+export type DataTableSelection =
+  | { mode: 'include'; ids: string[] }
+  | { mode: 'all'; excluded: string[] }
+
+// 正規化:string[] shorthand → { mode:'include' }(向後相容既有 consumer 傳 ID 陣列)
+function normalizeSelection(
+  input: string[] | DataTableSelection | undefined,
+): DataTableSelection | undefined {
+  if (input === undefined) return undefined
+  if (Array.isArray(input)) return { mode: 'include', ids: input }
+  return input
+}
+
+// union-aware「把 ids 設成 willSelect 狀態」純函式(對任意 toggle 順序封閉)
+function applySelectIds(
+  sel: DataTableSelection,
+  ids: string[],
+  willSelect: boolean,
+): DataTableSelection {
+  if (sel.mode === 'include') {
+    const set = new Set(sel.ids)
+    ids.forEach((id) => { if (willSelect) set.add(id); else set.delete(id) })
+    return { mode: 'include', ids: Array.from(set) }
+  }
+  // all 模式:選取 = 全集 − excluded → willSelect 移出 excluded;取消選取 加進 excluded
+  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: React.CSSProperties = { paddingBlock: 'var(--table-cell-py)', paddingInline: 'var(--table-cell-px)' }
 const HEADER_BG = 'bg-muted'
 
@@ -298,67 +394,29 @@ function columnSizeStyle(
   //
   // **flex-basis: baseSize(2026-05-06 v14.2)**:把 baseSize 當 explicit basis(不是 `0%`)。
   // 為什麼:flex item base = basis + padding(box-sizing: border-box content-box 行為)。前 `0%`
-  // basis → cell padding 變 base 一部分。display(padding 12)vs edit(padding 0,Field 接管)
-  // 兩態 base 不同 → flex 重分配 → user 報「Price cell 進 edit 寬度縮 12px」(verify by
-  // debug-v14-1-display-edit-rect-match.mjs:Price display 130.5 → edit 118.5 = -12px)。
-  // explicit basis = baseSize 讓 padding 不參與 base 計算 → display↔edit 寬度穩定。
+  // basis → cell padding 變 base 一部分。view(padding 12)vs edit(padding 0,Field 接管)
+  // 兩態 base 不同 → flex 重分配 → user 報「Price cell 進 edit 寬度縮 12px」
+  // (量測:Price view 130.5 → edit 118.5 = -12px)。
+  // explicit basis = baseSize 讓 padding 不參與 base 計算 → view↔edit 寬度穩定。
   return { flex: `1 1 ${baseSize}px`, minWidth: baseSize, maxWidth: maxSize }
 }
 
 const SYSTEM_COL_IDS = new Set([SELECT_COL_ID, '__drag__', '__actions__'])
 const isSystemColumn = (colId: string) => SYSTEM_COL_IDS.has(colId)
 
-// ── TruncateCell ─────────────────────────────────────────────────────────────
-// Shared ResizeObserver(2026-04-22 D3 perf audit):從 per-cell RO 改為全 DS 共用一個 RO
-// dispatch 到 per-element callback。10 col × 100 row = 1 RO(before:1000 RO)。
-// 跨 OS 一致的 RO 行為;element 卸載時 cleanup。
-
-type RoCallback = (entry: ResizeObserverEntry) => void
-let sharedResizeObserver: ResizeObserver | null = null
-const roCallbacks = new WeakMap<Element, RoCallback>()
-
-function getSharedRO(): ResizeObserver {
-  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: Element, cb: RoCallback): () => void {
-  const obs = getSharedRO()
-  roCallbacks.set(el, cb)
-  obs.observe(el)
-  return () => {
-    roCallbacks.delete(el)
-    obs.unobserve(el)
-  }
-}
-
-function TruncateCell({ children, className }: { children: React.ReactNode; className?: string }) {
-  const ref = React.useRef<HTMLSpanElement>(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 = <span ref={ref} className={cn('truncate min-w-0', className)}>{children}</span>
-  if (!isTruncated) return span
-  return <Tooltip><TooltipTrigger asChild>{span}</TooltipTrigger><TooltipContent>{children}</TooltipContent></Tooltip>
-}
-
-// ── L4 Row Drag: SortableRowContext (v2) ─────────────────────────────────────
-// v2:每 region(left / center / right)各 mount 一次 SortableRowProvider — 多個 useSortable
-// 共用同一 SortableContext / 同 row id 時,dnd-kit 內部以 id 為 unit 分發 transform / isDragging,
-// 各 hook instance 取得相同值,因此 mirror region 自然跟動(v1 mirror static bug 修正)。
-// listeners 仍只走 primary region(避免 pointer 事件雙重觸發);primary = left region 若存在否則 center。
-// `invalidDrop`(cross-parent over)走 prop 廣播給 DragHandleCell 切 cursor-not-allowed。
+// ── TruncatedText ── 2026-07-19:truncate+tooltip 引擎 + presentation 已抽成 SSOT primitive
+// `patterns/element-anatomy/truncated-text`(`<TruncatedText>` 消費 `useTruncated` hook)。原 file-local
+// shared RO(2026-04-22 D3 perf audit 的「全 DS 共用單一 RO」特性由 hook 承接)+ TruncateCell 已移除,
+// 改用 `<TruncatedText tooltip={children} className={...}>`(display 預設 inline,保 cell baseline)。
+// compound 欄位仍在 renderCellContent bypass(見下)—— 只 primitive string/number 走 TruncatedText。
+
+// ── L4 Row Drag: SortableRowContext(v15 Path B;2026-07-14 JSDoc 對齊實作)──────
+// 每 region(left / center / right)各 mount 一次 SortableRowProvider,依 role 分流(v15.4 split):
+//   primary → SourceRowProvider(useDraggable + useDroppable)= 唯一 drag source;
+//   mirror  → MirrorRowProvider(useDroppable only),isDragging 走 useDndContext active.id 同步。
+// 無 SortableContext / useSortable(v15.0 Path B 已砍,見檔頭 import 註解)。listeners 全走
+// RowDragHandle Button(v15.6 button-only;row 本身不接 listeners)。primary = left region 若存在否則 center。
+// `invalidDrop`(cross-parent over)走 prop 廣播給 RowDragHandle 切 cursor-not-allowed。
 interface SortableRowCtxValue {
   setNodeRef: (el: HTMLElement | null) => void
   role: 'primary' | 'mirror'
@@ -384,10 +442,11 @@ interface SortableRowCtxValue {
 }
 const SortableRowCtx = React.createContext<SortableRowCtxValue | null>(null)
 
-/** Per-region per-row sortable wrapper(v2 multi-instance pattern)。
- *  同 row.id 在 left/center/right 三 region 各 mount 一次 — useSortable 共享同 SortableContext
- *  state,各 instance 取得相同 transform → mirror 自動跟動。
- *  primary instance 額外提供 listeners 給 DragHandleCell;mirror 不提供避免雙觸發。 */
+/** Per-region per-row drag wrapper(v15.4 architectural split)。
+ *  同 row.id 在 left/center/right 三 region 各 mount 一次,但 hook mount tree 完全分離:
+ *  primary → SourceRowProvider(useDraggable + useDroppable);mirror → MirrorRowProvider
+ *  (useDroppable only,isDragging 由 useDndContext 同步)。activator / listeners 只給
+ *  primary 的 RowDragHandle Button(v15.6 button-only);mirror 不提供避免雙觸發。 */
 function SortableRowProvider(props: {
   id: string
   disabled?: boolean
@@ -427,7 +486,6 @@ function SourceRowProvider({
     droppable.setNodeRef(el)
   }, [draggable.setNodeRef, droppable.setNodeRef])
   const isDragging = draggable.isDragging
-  const style: React.CSSProperties = { ...dragSourceStyle(isDragging) }
   // a11y(2026-05-07 v15.10 codex P1 fix):button-only drag mode 下,row 本身不該成為
   // keyboard tab stop。dnd-kit `useDraggable.attributes` 含 `role="button" tabIndex=0
   // aria-roledescription="..."` 全給 activator 用,套到 row div 會讓每筆 row tabbable
@@ -435,10 +493,14 @@ function SourceRowProvider({
   // **拆分**:rowAttributes 留空(row 是 passive container)/ handleAttributes 全給
   // RowDragHandle Button(它是真 activator,Button 自帶 role/tabIndex 完全相容)。
   const handleAttrs = draggable.attributes as unknown as Record<string, unknown>
-  const ctxValue: SortableRowCtxValue = {
+  // 2026-07-05 D3 perf fix:ctxValue useMemo — 原每 render 新 object,RowDragHandle 的
+  // useLayoutEffect deps [rowEl, ctx] 在每次 DataTableInner render 都 teardown/重掛
+  // MutationObserver + window scroll/resize listener(×每個 visible primary row)。
+  // memo 後 identity 只在 drag 相關值真變(isDragging / invalidDrop 等)時才換。
+  const ctxValue: SortableRowCtxValue = React.useMemo(() => ({
     setNodeRef: setRefs,
     role,
-    style,
+    style: { ...dragSourceStyle(isDragging) },
     attributes: {},
     isDragging,
     // row 不接 listeners(button-only),baseRowDiv `{...(extra?.listeners ?? {})}` 自動 noop
@@ -451,7 +513,7 @@ function SourceRowProvider({
     handleListeners: draggable.listeners as unknown as Record<string, unknown> | undefined,
     handleAttributes: handleAttrs,
     invalidDrop,
-  }
+  }), [setRefs, role, isDragging, draggable.setActivatorNodeRef, draggable.listeners, handleAttrs, invalidDrop])
   return <SortableRowCtx.Provider value={ctxValue}>{children(ctxValue)}</SortableRowCtx.Provider>
 }
 
@@ -479,7 +541,9 @@ function MirrorRowProvider({
   const droppable = useDroppable({ id, disabled, data: { type: 'row' } })
   const dndCtx = useDndContext()
   const isDragging = dndCtx.active?.id === id
-  const ctxValue: SortableRowCtxValue = {
+  // 2026-07-05 D3 perf fix:ctxValue useMemo(同 SourceRowProvider — 消掉 RowDragHandle
+  // effect 的每 render observer/listener churn;mirror 雖不渲 handle,identity 穩定仍省下游 diff)
+  const ctxValue: SortableRowCtxValue = React.useMemo(() => ({
     setNodeRef: droppable.setNodeRef,
     role,
     style: { ...dragSourceStyle(isDragging) },
@@ -491,18 +555,19 @@ function MirrorRowProvider({
     handleListeners: undefined,
     handleAttributes: {},
     invalidDrop,
-  }
+  }), [droppable.setNodeRef, role, isDragging, invalidDrop])
   return <SortableRowCtx.Provider value={ctxValue}>{children(ctxValue)}</SortableRowCtx.Provider>
 }
 
-/** DraggableHeaderCell — wrap header cell 跟 dnd-kit useSortable 接軌(2026-05-06 v14.2)。
+/** DraggableHeaderCell — wrap header cell 跟 dnd-kit useDraggable + useDroppable 接軌
+ *  (2026-05-06 v14.2;v15.0 Path B 改分離 hooks,無 SortableContext)。
  *
  *  Why wrap-not-rewrite:`headerCellEl` 既有邏輯複雜(sort / resize / select column / right region 等),
- *  改 inline useSortable 入侵性高。本 wrapper cloneElement 注入 ref / style / listeners → 既有 render
+ *  改 inline useDraggable/useDroppable 入侵性高。本 wrapper cloneElement 注入 ref / style / listeners → 既有 render
  *  保持 untouched,單一職責 = 加 drag affordance。
  *
  *  Behavior:
- *    - useSortable 永遠 call(Rules of Hooks)— `disabled=true` 時不啟動 listeners
+ *    - useDraggable + useDroppable 永遠 call(Rules of Hooks)— `disabled=true` 時不啟動 listeners
  *    - `data: { type: 'column', columnId }` 餵 dnd-kit handleDragStart / handleDragEnd 區分 row/column drag
  *    - 注入 ref(setNodeRef)+ transform style + transition + opacity(drag 時 source invisible,DragOverlay 顯 ghost)
  *    - draggable 時注入 attributes + listeners + cursor:grab / `data-column-id` (DragOverlay snapshot 用)
@@ -546,12 +611,33 @@ function DraggableHeaderCell({
     : dropIndicatorSide === 'after'
     ? dropIndicatorColumn.pseudoAfter
     : ''
+  // dnd-kit KeyboardSensor 的 activator = listeners.onKeyDown,掛在整個 header cell 上(column
+  // 無獨立 activator node,不像 row drag 的 button-only handle)。巢狀互動 descendant(more-menu
+  // 按鈕 / resize separator / 排序 chevron)的 Enter/Space 冒泡到此 → dnd-kit preventDefault 啟動
+  // 欄位拖曳,吃掉按鈕原生啟動。包一層 guard:事件來自互動 descendant(非 header cell 本身)時
+  // 交回原生,不啟動拖曳。對齊 dnd-kit「activator node 排除互動 descendant」idiom。
+  const rawListeners = draggable.listeners as Record<string, ((e: React.SyntheticEvent) => void) | undefined> | undefined
+  const guardedListeners: Record<string, unknown> | undefined = rawListeners
+    ? {
+        ...rawListeners,
+        onKeyDown: (e: React.KeyboardEvent) => {
+          const target = e.target as HTMLElement
+          if (
+            target !== e.currentTarget &&
+            target.closest('button, a, input, select, textarea, [role="menuitem"], [role="separator"]')
+          ) {
+            return
+          }
+          rawListeners.onKeyDown?.(e)
+        },
+      }
+    : rawListeners
   return React.cloneElement(children as React.ReactElement<Record<string, unknown>>, {
     ref: setRefs,
     style: { ...(childProps.style ?? {}), ...dragStyle },
     'data-column-id': id,
     'data-column-locked': isLocked || undefined,
-    ...(disabled ? {} : { ...draggableAttrs, ...(draggable.listeners as unknown as Record<string, unknown>) }),
+    ...(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。
@@ -562,8 +648,9 @@ function DraggableHeaderCell({
 
 /** Row drag handle — Portal-rendered, position:fixed 真正水平置中於 table outer border line(Jira canonical)。
  *
- *  v15.2 重構:**Button 純視覺 affordance**,不再 spread drag listeners — 改由 row div 整列接 listeners
- *  (TreeView SSOT)。Button 只負責顯示「此 row 可拖」的視覺暗示。
+ *  v15.6 button-only drag(推翻 v15.2「整列接 listeners」,2026-07-14 JSDoc 對齊):Button =
+ *  唯一 activator,接 handleSetActivatorNodeRef + handleListeners(SourceRowProvider ctx);
+ *  row div 不接 listeners(rowListeners=undefined),row click 保留給 select / open detail 等 UX。
  *
  *  Why Portal + position:fixed(2026-05-05 v4):
  *    DataTable 結構含三層 overflow-hidden(outer wrapper / leftBody / row),用 absolute + translate-x:-50%
@@ -604,11 +691,16 @@ function RowDragHandle({ disabled, anyDragActive }: { disabled: boolean; anyDrag
       // v15.1:drag 期間 source button hide(visible 邏輯已 guard isDragging),
       // 此處只報「真實 hover」狀態,不疊 isDragging mask。
       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 // table outer 左 border line position(viewport coords)
+      // 2026-07-05 D3 perf fix:prev 值比對 — 位置/hover 沒變時回傳 prev reference,
+      // React Object.is bail out(原每 scroll frame 無條件新 object → 每個 visible handle
+      // 每 frame 必 re-render Button + Tooltip + portal,即使位置根本沒動)。
+      setPos((prev) =>
+        prev && prev.top === top && prev.left === left && prev.rowHovered === rowHovered
+          ? prev
+          : { top, left, rowHovered },
+      )
     }
 
     update()
@@ -623,6 +715,11 @@ function RowDragHandle({ disabled, anyDragActive }: { disabled: boolean; anyDrag
     // useOverflowCount fix `combobox.tsx:130`)。
     let scrollRafId = 0
     const onScroll = () => {
+      // D3 NO-SAMPLE audit(2026-08-02):non-hovered virtual rows still share the window
+      // listener, but their hidden handles do not need rect reads. Without this guard a
+      // 50-row virtual window scheduled 50 rAF callbacks + getBoundingClientRect calls
+      // for every scroll frame even though only one handle can be visible.
+      if (!rowEl.hasAttribute('data-hovered') && !buttonHovered && !ctx.isDragging) return
       if (scrollRafId) cancelAnimationFrame(scrollRafId)
       scrollRafId = requestAnimationFrame(() => {
         scrollRafId = 0
@@ -638,7 +735,7 @@ function RowDragHandle({ disabled, anyDragActive }: { disabled: boolean; anyDrag
       window.removeEventListener('scroll', onScroll, true)
       window.removeEventListener('resize', onScroll)
     }
-  }, [rowEl, ctx])
+  }, [rowEl, ctx, buttonHovered])
 
   // 永遠 render anchor span(讓 anchorRef 可拿到 row element)。
   // A3 fix(2026-05-05):顯式 `top:0 left:0 pointer-events:none` — 雖 width/height=0 不該佔
@@ -694,13 +791,13 @@ function RowDragHandle({ disabled, anyDragActive }: { disabled: boolean; anyDrag
         // 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。
+        // 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 ? 0.5 : (canDrag ? 1 : 'var(--opacity-disabled)' as unknown as number))
+          ? (ctx.isDragging ? 'var(--opacity-disabled)' as unknown as number : (canDrag ? 1 : 'var(--opacity-disabled)' as unknown as number))
           : 0,
         pointerEvents: visible ? 'auto' : 'none',
-        transition: 'opacity 150ms ease',
       }}
       className={cn(
         // 2026-05-12 debug fix(user 抓「hover 還是透明」)— Round 4.5 我未授權加
@@ -712,6 +809,7 @@ function RowDragHandle({ disabled, anyDragActive }: { disabled: boolean; anyDrag
         // 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 接管)
@@ -738,25 +836,80 @@ function RowDragHandle({ disabled, anyDragActive }: { disabled: boolean; anyDrag
 }
 
 // ══════════════════════════════════════════════════════════════════════════════
-// AG Grid 模式：header 在 scroll 外面，body 是唯一的垂直 scroll container。
+// AG Grid 模式：header 在 scroll 外面，V scroll 在 center-body（AR44 後現況）。
 //
 //  table
 //  ├── header（固定頂部，不在 scroll 內）
 //  │   ├── left-header
 //  │   ├── center-header（overflow:hidden，JS sync scrollLeft）
 //  │   └── right-header
-//  └── body-viewport（overflow-y:auto，display:flex）
-//      ├── left-body（overflow:hidden）
-//      ├── center-body（overflow-x:auto, overflow-y:hidden）
-//      └── right-body（overflow:hidden）
+//  └── body-viewport（display:flex，無 overflow — AR44 後不再是 scroll container）
+//      ├── left-body（overflow:hidden，JS sync scrollTop）
+//      ├── center-body（overflow-x:auto, overflow-y:auto — 唯一 V scroll，
+//      │               onCenterBodyScroll 同步兩側 scrollTop + header scrollLeft）
+//      └── right-body（overflow:hidden，JS sync scrollTop）
 //
-// 不用 CSS sticky。Header 永遠在頂部。
+// 不用 CSS sticky。Header 永遠在頂部。細節見下方「JS scroll sync(AR44)」註解。
 // ══════════════════════════════════════════════════════════════════════════════
 
+// ── MemoCellSlot(2026-07-05 D3 perf fix)────────────────────────────────────
+// cell-registry 2026-05-13 已把每個 cell type 包成 module-level cached `React.memo(CellWithSurface)`,
+// 但 renderCellContent 每次 render 傳 3 個全新 inline closure(onCommit / onCommitLive /
+// onRequestEdit)+ `meta ?? {}` 新 object → memo shallow-compare 100% fail,防線靜默失效
+// (DataTableInner 任何 re-render — scroll / resize / drag / spreadsheet 選取 / portal keystroke —
+// 都讓全部 visible cells 的 Field view subtree 整棵重渲)。
+// Fix:中介 memo slot — 從 parent 接 stable callback(commitCell / cancelCellEdit / onCellCommit /
+// enterCellEdit)+ primitive rowId / colId,在 slot 內 useCallback 綁 per-cell closure;
+// props 全 primitive / stable reference → memo 真命中,unchanged cells render 成本歸零。
+// Cite world-class:AG Grid「cell renderer stable reference」/ MUI X DataGrid memoized subcomponents。
+const EMPTY_META: Record<string, unknown> = {}
+
+interface MemoCellSlotProps {
+  Cell: React.ComponentType<CellComponentProps>
+  rowId: string
+  colId: string
+  // any-allow: free-form column value(consumer-defined,同 CellComponentProps.value)
+  value: any
+  // any-allow: free-form consumer meta bag(同 CellComponentProps.meta)
+  meta: Record<string, any>
+  mode: 'view' | 'edit'
+  size: 'sm' | 'md' | 'lg'
+  autoRowHeight: boolean
+  isEditable: boolean
+  onCommitCell: (rowId: string, colId: string, next: unknown) => void
+  onCancelCell: (rowId: string, colId: string) => void
+  onCellCommitLive?: (rowId: string, colId: string, next: unknown) => void
+  onEnterEdit: (rowId: string, colId: string) => void
+}
+
+const MemoCellSlot = React.memo(function MemoCellSlot({
+  Cell, rowId, colId, value, meta, mode, size, autoRowHeight,
+  isEditable, onCommitCell, onCancelCell, onCellCommitLive, onEnterEdit,
+}: MemoCellSlotProps) {
+  const onCommit = React.useCallback((next: unknown) => onCommitCell(rowId, colId, next), [onCommitCell, rowId, colId])
+  const onCommitLive = React.useCallback((next: unknown) => 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 (
+    <Cell
+      value={value}
+      meta={meta}
+      mode={mode}
+      size={size}
+      autoRowHeight={autoRowHeight}
+      isEditable={isEditable}
+      onCommit={onCommit}
+      onCommitLive={onCommitLive}
+      onCancel={onCancel}
+      onRequestEdit={onRequestEdit}
+    />
+  )
+})
+
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 function DataTableInner<TData>(
   {
-    columns, data, size = 'md', autoRowHeight = false, height = '400px',
+    columns, data, size = 'md', autoRowHeight = false, height: heightProp,
     overscan = 5, emptyState, enableHover = true, bordered,
     estimateRowHeight, tableOptions, rowActions, cellErrors,
     pinnedLeftColumns, pinnedRightColumns, inlineEdit = false,
@@ -776,22 +929,25 @@ function DataTableInner<TData>(
     experimentalSpreadsheetOverlay = false,
     experimentalActiveEditorController = false,
     spreadsheetMode = false,
+    pagination,
     className, ...props
   }: DataTableProps<TData>,
   ref: React.ForwardedRef<HTMLDivElement>
 ) {
+  // L5 分頁 × height 預設(2026-07-06):未顯式傳 height 時 —— 分頁 = 'auto' 自然高度
+  // (頁碼是唯一導覽通道,不疊 body 內捲動;Ant Table 無預設高度罩慣例),
+  // 未分頁 = 既有 '400px' 預設不變。顯式傳 height 一律尊重(prop docblock 有完整規則)。
+  const height = heightProp ?? (pagination ? 'auto' : '400px')
   // ── L4 Inline edit state ──
   // editingCellId: `${rowId}__${columnId}` 標識當前進 edit mode 的 cell;null = 無
   const [editingCellId, setEditingCellId] = React.useState<string | null>(null)
   // Phase 7 D.3 portal Field virtualizer unmount preserve draft(2026-05-10 per codex Q-B4 verdict):
   // Lifted draft state in DataTable — Cell DOM unmount(virtualizer scroll out)時 draft 不丟,
   // mount-back 時 portal Field value=draft 而非 row.value,user 編輯中字保留。
-  // editingCellId 變時 useEffect reset draft 到新 cell row.value(全新 edit session)。
+  // draft 生命週期(2026-07-05 D4 fix):cancelCellEdit / commitCell 清 draft;Tab 換格
+  // (handleEditTab)先 commit 當前 draft 再換格 — 原註解宣稱「editingCellId 變時 useEffect
+  // reset draft」的 effect 從未存在,曾致 Tab 換格後下一格顯示上一格草稿。
   const [editingDraft, setEditingDraft] = React.useState<unknown>(undefined)
-  const exitEdit = React.useCallback(() => {
-    setEditingCellId(null)
-    setEditingDraft(undefined)
-  }, [])
 
   // ── Slice D Step 4 spreadsheet semantics state(2026-05-10) ──
   // selectedCellId:`${rowId}:${colId}` Excel-like 選取(click 1)
@@ -820,14 +976,44 @@ function DataTableInner<TData>(
     document.addEventListener('pointerdown', handler, true)
     return () => document.removeEventListener('pointerdown', handler, true)
   }, [spreadsheetMode, selectedCellId, rangeAnchor])
+  // 2026-07-05 D4 fix:edit 退出(commit / cancel)後還原 spreadsheet selection 到該 cell +
+  // 收回焦點到 table root — 原本只清 editingCellId,editor unmount 後 document.activeElement
+  // 掉到 body、selection 不還原 → 每次編輯後鍵盤導覽死巷(方向鍵全滅、必須滑鼠重點),違反
+  // datatable-spreadsheet-rfc.md Contract 11「退出後還給 active cell」(對齊 Excel / AG Grid / Sheets)。
+  const restoreCellSelection = React.useCallback((rowId: string, colId: string) => {
+    if (!spreadsheetMode) return
+    const cellId = `${rowId}:${colId}`
+    setSelectedCellId(cellId)
+    setRangeAnchor(cellId)
+    setRangeFocus(null)
+    // 等 editor unmount 完成後才收回焦點;activeElement 非 body(user 點了其他 focusable /
+    // Tab 換格後下一格 editor autoFocus)時不搶焦點。
+    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: string, colId: string, next: unknown) => {
       onCellCommit?.(rowId, colId, next)
       setEditingCellId(null)
       setEditingDraft(undefined)  // Phase 7:commit 後清 draft
+      restoreCellSelection(rowId, colId)  // 2026-07-05 D4:commit 後 selection 還原(Contract 11)
     },
-    [onCellCommit],
+    [onCellCommit, restoreCellSelection],
   )
+  // cancel 路徑(Esc / popover dismiss)— 同 commit 還原 selection;取代舊無參數 exitEdit
+  const cancelCellEdit = React.useCallback((rowId: string, colId: string) => {
+    setEditingCellId(null)
+    setEditingDraft(undefined)
+    restoreCellSelection(rowId, colId)
+  }, [restoreCellSelection])
+  // edit 進入點(MemoCellSlot onEnterEdit 消費;stable identity 維持 memo 命中)
+  const enterCellEdit = React.useCallback((rowId: string, colId: string) => {
+    setEditingCellId(cellEditId(rowId, colId))
+  }, [])
   // 判 column meta.editable 對特定 row 是否成立(支援 fn)
   // column meta 是 free-form consumer bag(同 renderTypedValue any policy),不適合窄型化
   const isCellEditable = React.useCallback(
@@ -839,28 +1025,13 @@ function DataTableInner<TData>(
     },
     [],
   )
-  // 2026-05-13 Stream C Cluster B Q3 ship(per codex Q3 verdict + user 拍板「全部馬不停蹄做完」):
-  // Mirror isCellEditable pattern。`column.meta.disabled` 接 bool 或 (row) => boolean fn。
-  // cell disabled → (a) TD 加 `bg-disabled cursor-not-allowed` + 抑制 hover, (b) inner Field
-  // 透過 isDisabled prop 走 mode='disabled'(各 Field type 內部具體 disabled token,非 wrapper blanket opacity),
-  // (c) edit entry condition: `cellEditable && !cellDisabled`。
-  const isCellDisabled = React.useCallback(
-    // any-allow: free-form consumer meta — same rationale as L143 renderTypedValue
-    (meta: Record<string, any> | undefined, row: unknown): boolean => {
-      const d = meta?.disabled
-      if (typeof d === 'function') return d(row) === true
-      return d === true
-    },
-    [],
-  )
-  // 2026-05-13:canEditCell helper consolidation(per codex V4 follow-up + user「沒理由不做」拍板)
-  // 抽 4-site repeated `editable && !disabled` pattern。3 path sites(keyboard / Tab / InteractionLayer)
-  // call canEditCell;另 2 sites(renderCellContent + onEditableCellClick)用 already-computed `editable`/
-  // `disabled` 變數(因為 disabled 還要單獨給 isDisabled prop + bg-disabled class),不 collapse to helper。
+  // 2026-07-16 round16:cell「disabled」態廢除(世界級 grid 無 disabled cell;meta.disabled 全庫 0 消費)。
+  // 鎖定 cell = `editable:(row)=>false`(= isCellEditable 模型),非灰化 disabled 態。原 isCellDisabled
+  // helper + bg-disabled TD 灰化 + isDisabled prop 全移除;canEditCell 收斂為 isCellEditable。
   const canEditCell = React.useCallback(
     (meta: Record<string, unknown> | undefined, row: unknown): boolean =>
-      isCellEditable(meta, row) && !isCellDisabled(meta, row),
-    [isCellEditable, isCellDisabled],
+      isCellEditable(meta, row),
+    [isCellEditable],
   )
   const [sorting, setSorting] = React.useState<SortingState>(tableOptions?.state?.sorting as SortingState ?? [])
 
@@ -874,9 +1045,9 @@ function DataTableInner<TData>(
   // ── L2 Selection state ──
   const enabled = selectable !== false
   const mode = selectable === 'single' ? 'single' : 'multi'
-  const [selection, setSelection] = useControllable<string[]>({
-    value: selectionProp,
-    defaultValue: defaultSelection ?? [],
+  const [selection, setSelection] = useControllable<DataTableSelection>({
+    value: normalizeSelection(selectionProp),
+    defaultValue: normalizeSelection(defaultSelection) ?? { mode: 'include', ids: [] },
     onChange: onSelectionChange,
   })
   // Shift-click anchor:存最後一次「單擊」的 row id,shift-click 時做區間選
@@ -942,6 +1113,20 @@ function DataTableInner<TData>(
   // 注意:`...tableOptions` 必 spread 在 `state` 前,否則 user 傳的 tableOptions 會
   // 整個 override 掉我們組的 state(含 __select__ 自動 pinning + columnOrder 注入)。
   // 之前 bug:checkbox column 跑到右邊 = 此處 spread 順序錯。
+  // ── L5 分頁 state(2026-07-06)──────────────────────────────────────────────
+  // 共用模式(user 拍板):<Pagination> 獨立元件為頁碼視覺 SSOT,DataTable 內建接 TanStack
+  // 分頁模型消費它(Ant Table 消費 Pagination / Atlassian DynamicTable rowsPerPage / MUI
+  // DataGrid 同派;shadcn data-table 教學同款「分頁 render 在元件 JSX 內」)。
+  const paginationEnabled = !!pagination
+  const paginationOpts = typeof pagination === 'object' ? pagination : undefined
+  const [pageSizeState, setPageSizeState] = React.useState(paginationOpts?.pageSize ?? 20)
+  // 1-based 對外(對齊 Pagination / Ant);餵 TanStack state 時換算 0-based
+  const [currentPage, setCurrentPage] = useControllable<number>({
+    value: paginationOpts?.page,
+    defaultValue: paginationOpts?.defaultPage ?? 1,
+    onChange: paginationOpts?.onPageChange,
+  })
+
   const table = useReactTable({
     ...tableOptions,
     data, columns: columnsWithSelection,
@@ -951,6 +1136,9 @@ function DataTableInner<TData>(
       // columnPinning + columnOrder 在 user state 後 override,確保 __select__ 永遠左
       columnPinning: { left: effectivePinnedLeft, right: pinnedRightColumns ?? [] },
       ...(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)
@@ -968,6 +1156,8 @@ function DataTableInner<TData>(
     getSortedRowModel: getSortedRowModel(),
     // L4 nested rows:啟用 expanded row model(consumer 透過 tableOptions.getSubRows + state.expanded forward)
     getExpandedRowModel: getExpandedRowModel(),
+    // L5 分頁:條件掛載(TanStack 官方:pagination 與 virtualization 為互斥替代策略)
+    ...(paginationEnabled ? { getPaginationRowModel: getPaginationRowModel() } : {}),
     getRowId: 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
@@ -982,10 +1172,20 @@ function DataTableInner<TData>(
   })
 
   // v13.2:onColumnResize callback 透過 useEffect 觀測 columnSizing state 變動 fire(uncontrolled state pattern)
+  // 2026-07-06 D3 fix:兌現 prop docblock「commit-on-pointerup,非 live」契約 —
+  // columnResizeMode:'onChange' 讓 drag 中 columnSizing 每 mousemove 變一次(視覺即時跟動,
+  // 保留),原 effect 無 gate → callback 每 mousemove fire 一次;docblock 明文建議 consumer
+  // 在此 callback 做 width persistence(localStorage / URL / API)= 每 mousemove I/O。
+  // 改以 TanStack columnSizingInfo.isResizingColumn 為訊號:drag 進行中不 fire、也不推進
+  // snapshot(保留 drag 前基準);pointerup(isResizingColumn 轉 false)才 diff snapshot,
+  // fire 一次最終寬度。非 drag 路徑(「自動調整寬度」menu 的 setColumnSizing)不經
+  // isResizingColumn,行為不變。
   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]) {
@@ -993,10 +1193,17 @@ function DataTableInner<TData>(
       }
     })
     prevColumnSizingRef.current = columnSizingState
-  }, [columnSizingState, onColumnResize])
+  }, [columnSizingState, isResizingColumn, onColumnResize])
 
   const { rows } = table.getRowModel()
   const isEmpty = rows.length === 0
+
+  // L5 分頁:filter / data 縮小時 TanStack 不自動 clamp 當前頁(會停在空頁);對齊 MUI X 自動 clamp
+  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'
   // Fill-parent mode:height='100%' / '100vh' / 'fill' 等百分比 / 視口語義 → outer flex column + body flex-1 撐滿。
   // 固定 px/rem 仍維持 maxHeight cap 行為(資料少 = 內容高度,資料多 = 上限後 scroll)— 對齊既有 stories 預期。
@@ -1008,7 +1215,8 @@ function DataTableInner<TData>(
   // direct render 完全 bypass 此 race,且小資料下虛擬化沒效益(浪費 reflow)。
   // 對齊 AG Grid `suppressVirtualization` / TanStack Table virtualization-when-needed idiom。
   const VIRTUAL_THRESHOLD = 30
-  const useVirtual = hasHeightConstraint && !isEmpty && rows.length > VIRTUAL_THRESHOLD
+  // L5 分頁互斥:分頁後每頁 rows ≤ pageSize,虛擬化無效益(TanStack 官方:兩者為互斥替代策略)
+  const useVirtual = !paginationEnabled && hasHeightConstraint && !isEmpty && rows.length > VIRTUAL_THRESHOLD
   const hasRowActions = !!rowActions
 
   // Refs
@@ -1029,7 +1237,7 @@ function DataTableInner<TData>(
   // 2026-05-06 v10 DragOverlay canonical:retire windowed sticky range extractor (v4-v9 workaround)。
   // 改用 `<DragOverlay>` portal 把 source row 視覺解耦 — source 即使 unmount(virtual scroll out)
   // overlay 仍 render 由 cloned outerHTML 提供視覺。dnd-kit transform / collision 走 active item id
-  // (id 永遠在 SortableContext.items 集合,跟 hook instance mount 狀態無關)。
+  // (DndContext store 以 active id 追蹤,跟 hook instance mount 狀態無關;v15 無 SortableContext)。
   // 對齊 dnd-kit GitHub #1674 + drag-overlay docs canonical「virtualized list MUST use DragOverlay」。
   // overscan 仍輕微拉高(避免 source row 旁邊 rows 也 unmount 致使 hover signal 計算抖動)。
   const effectiveOverscan = enableRowDrag ? Math.max(overscan, 5) : overscan
@@ -1060,6 +1268,8 @@ function DataTableInner<TData>(
   // 後續 measureElement 修正到 6×40 = 240,差 24px 視覺看起來像「table 慢慢長高」。fix = estimate
   // 預設 size-aware 對齊 token(見下方 estimateRowHeight default 計算)。
   const [bodyMaxHeight, setBodyMaxHeight] = React.useState<number | null>(null)
+  // L5 分頁 × isFillHeight(2026-07-07 C12):bar 高度量測用 — compute() 需扣分頁列 footprint
+  const paginationBarRef = React.useRef<HTMLDivElement | null>(null)
   React.useLayoutEffect(() => {
     if (!isFillHeight) { setBodyMaxHeight(null); return }
     // **R4 真根因 fix(2026-05-09 v2 — codex Q3.6 root cause + Q3.9 reproduce verified)**:
@@ -1102,7 +1312,15 @@ function DataTableInner<TData>(
                 ?? tableRef.current.getBoundingClientRect().height
       const headerEl = tableRef.current.firstElementChild as HTMLElement | null
       const headerH = headerEl?.getBoundingClientRect().height ?? 0
-      const next = Math.max(0, slotH - headerH)
+      // L5 分頁 × isFillHeight(2026-07-07 C12):啟用分頁時 parent slot = composedContent
+      // wrapper(含分頁列 + tight gap),body 可用高必扣分頁列 footprint,否則 body 撐滿
+      // 把分頁列擠出 / 被 overflow 裁掉
+      const barEl = paginationBarRef.current
+      const barFootprint = barEl
+        ? barEl.getBoundingClientRect().height +
+          (parseFloat(getComputedStyle(barEl.parentElement as Element).rowGap) || 0)
+        : 0
+      const next = Math.max(0, slotH - headerH - barFootprint)
       // Diff guard < 4px(濾 micro-step,real resize δ 必 ≫ 4px)
       if (lastValue != null && Math.abs(next - lastValue) < 4) return
       lastValue = next
@@ -1149,10 +1367,9 @@ function DataTableInner<TData>(
 
   // ── Phase 9 Issue 1 fix(2026-05-10):range cells lifted compute + Set ────
   // 計算 spreadsheet range cell IDs(Shift+click rectangle from anchor↔focus),
-  // 提供:
-  //   1. `rangeCellIds` array → pass to layer for outer ring 4 line div boundary
-  //   2. `rangeCellIdSet` Set → cell wrapper data-range-cell attr for cell-bg fill
-  //      (per codex Q1 verdict:bg fill 移到 cell bg layer 不在 overlay,內容才不被蓋)
+  // 提供 `rangeCellIdSet` Set → cell wrapper data-range-cell attr for cell-bg fill
+  // (per codex Q1 verdict:bg fill 走 cell bg layer 不在 overlay,內容才不被蓋;
+  //  layer 的 outer ring / rangeCellIds prop 已 retire — 2026-07-14 對齊清理)
   const rangeCellIds = React.useMemo<string[] | undefined>(() => {
     if (!spreadsheetMode || !rangeAnchor || !rangeFocus || rangeAnchor === rangeFocus) return undefined
     const parseCell = (id: string) => {
@@ -1209,7 +1426,13 @@ function DataTableInner<TData>(
     return () => obs.disconnect()
   }, [hasLeft, hasRight, rows.length])
 
-  const rowHeight = `h-table-row-${size}`
+  // 2026-07-09 root-cause fix(user 以 GitHub Pages 對比抓出 regression):
+  //   舊 `h-table-row-${size}` 模板字串 Tailwind **靜態掃描看不到** → `.h-table-row-{sm,md,lg}` 規則
+  //   唯一靠 uiSize.spec.md 裡的 literal 被 content-detection 掃到才生成;戰役期間掃描樹變動後未生成
+  //   → 規則消失 → row 塌成「內容高度」(非編輯 33px / 編輯 44px)而非固定 token 40px,連帶選取控件與
+  //   列文字對不齊。改用 literal map(對齊 field-wrapper cva 的 `h-field-md` literal 慣例),Tailwind
+  //   永遠掃得到、不再依賴脆弱的 spec.md literal → 永不再漂移。
+  const rowHeight = { sm: 'h-table-row-sm', md: 'h-table-row-md', lg: 'h-table-row-lg' }[size] ?? 'h-table-row-md'
 
   // ── Cross-region row hover (2026-04-22 D3 perf audit):event delegation 改 per-row closure
   // 舊:每 row 建 `{ onMouseEnter, onMouseLeave }` + 2 arrow functions → 100 row = 200 closures/render
@@ -1249,56 +1472,58 @@ function DataTableInner<TData>(
   const hoverProps = (_idx: number): Record<string, never> => ({})
 
   // ── Cell render(Phase C 2026-05-05 — type-keyed registry SSOT)──
-  // 命中 columnType → 走 cellRegistry(display / edit mode 同元件 with `mode` prop);
+  // 命中 columnType → 走 cellRegistry(view / edit mode 同元件 with `mode` prop);
   // 無 columnType → consumer 自訂 cell.columnDef.cell。
   const renderCellContent = (cell: ReturnType<typeof rows[number]['getVisibleCells']>[number]) => {
     const meta = cell.column.columnDef.meta
     const colType = meta?.type as ColumnType | undefined
     const wrap = autoRowHeight && meta?.wrap === true
-    // 已知 compound 欄位(Tag / PersonDisplay / LinkInput 等自帶 layout)直接 bypass TruncateCell,
+    // 已知 compound 欄位(Tag / PersonDisplay / LinkInput 等自帶 layout)直接 bypass TruncatedText,
     // 因為 `truncate` 的 inline baseline context 會破壞自訂 layout 的垂直對齊。
-    // 2026-05-09 D-path:date / time 加入(showDisplayEndIcon → Field naked-display 需 full width 才能
-    //   右對齊 ItemSuffix。TruncateCell 的 `<span truncate min-w-0>` block-display 會 collapse Field
+    // 2026-05-09 D-path:date / time 加入(showDisplayEndIcon → Field naked-view 需 full width 才能
+    //   右對齊 ItemSuffix。TruncatedText 的 `<span truncate min-w-0>` block-display 會 collapse Field
     //   to content size,讓 Calendar / Clock icon 緊貼 value text 而非右邊緣)。
     const isKnownCompound = colType === 'select' || colType === 'multiSelect' || colType === 'person' || colType === 'multiPerson' || colType === 'url' || colType === 'date' || colType === 'time'
     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: React.ReactNode
     if (colType) {
       const Cell = resolveCellComponent(colType)
       // 2026-05-10 Slice D Step 5(D.3 portal Field):當 portal flag 啟 + cell 編輯中 →
-      // cell 保持 display mode(SSOT preserved per codex Q6.2),portal layer 渲 edit Field 在上。
-      // 預設 inline-edit:isEditingThisCell ? edit : display。
-      // 2026-05-13 Q3 cell-disabled:disabled cell 永遠 display lifecycle(state overlay,不進 edit)。
-      const cellMode: 'edit' | 'display' =
+      // cell 保持 view mode(SSOT preserved per codex Q6.2),portal layer 渲 edit Field 在上。
+      // 預設 inline-edit:isEditingThisCell ? edit : view。
+      const cellMode: 'edit' | 'view' =
         (experimentalActiveEditorController && isEditingThisCell)
-          ? 'display'
-          : (isEditingThisCell && !disabled) ? 'edit' : 'display'
+          ? 'view'
+          : isEditingThisCell ? 'edit' : 'view'
+      // 2026-07-05 D3 perf fix:改經 MemoCellSlot — 原 inline closure props 讓 CellWithSurface
+      // memo 100% miss(詳 MemoCellSlot 檔頭註解)。
       content = (
-        <Cell
+        <MemoCellSlot
+          Cell={Cell}
+          rowId={rowId}
+          colId={colId}
           value={cell.getValue()}
-          meta={meta ?? {}}
+          meta={meta ?? EMPTY_META}
           mode={cellMode}
           size={size}
           autoRowHeight={autoRowHeight}
           isEditable={editable}
-          isDisabled={disabled}
-          onCommit={(next) => commitCell(rowId, colId, next)}
-          onCommitLive={(next) => 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())
     }
     // Consumer 自訂 cell(無 colType)若回傳 React element,視為 compound — consumer 自己處理
-    // 對齊與截斷。回傳 primitive(string / number)才走 TruncateCell。
-    // 理由:TruncateCell 的 `span.truncate` 強制 white-space:nowrap + inline baseline,
+    // 對齊與截斷。回傳 primitive(string / number)才走 TruncatedText。
+    // 理由:TruncatedText 的 `span.truncate` 強制 white-space:nowrap + inline baseline,
     // 對 inline-flex / icon+text 自訂結構會拉歪(見 circular-progress sync table 案例)。
     // **edit mode bypass**(2026-05-05 v9 Bug 2 修):editing cell 內部是 Field 控件
     // (Input/Textarea/Select etc.)自管 layout + 替代元素(textarea)不該被包進 inline span
@@ -1307,15 +1532,15 @@ function DataTableInner<TData>(
     return isEditingThisCell ? content
       : wrap ? <span className="break-words min-w-0">{content}</span>
       : (isKnownCompound || isConsumerCompound) ? content
-      : <TruncateCell>{content}</TruncateCell>
+      : <TruncatedText>{content}</TruncatedText>
   }
 
   // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
 
   // 2026-05-09 D-path retired:`getEditIndicator(colType)` parallel system 移除。
-  // Indicator authority 從 DataTable cellEl 移交 **Field naked-display branch via `showDisplayEndIcon` opt-in**
-  //   — Select / TimePicker / DatePicker / Combobox / PeoplePicker 5 picker 的 display mode 內建
+  // Indicator authority 從 DataTable cellEl 移交 **Field naked-view branch via `showDisplayEndIcon` opt-in**
+  //   — Select / TimePicker / DatePicker / Combobox / PeoplePicker 5 picker 的 view mode 內建
   //   `<ItemSuffix>` 渲對應 trigger icon(同 edit DOM 結構)。LinkInput URL anchor 例外(無 suffix)。
   // SSOT chain:cell-registry.tsx(opt-in props)→ Field component(intrinsic icon + ItemSuffix DOM)→
   //   item-anatomy ItemPrefix/ItemSuffix layout SSOT。詳 `.claude/planning/cell-indicator-ssot-rfc.md`。
@@ -1325,8 +1550,8 @@ function DataTableInner<TData>(
   const dragDisabled = sorting.length > 0
 
   // ── L4 Row drag v2:nested rows + parent map ─────────────────────────────────
-  // v2 cross-parent fix:全 row 進 SortableContext.items(含 sub-rows),custom collisionDetection
-  // 過濾掉 cross-parent over candidates,保留「同 parent siblings」。沒命中 → invalid drop signal。
+  // v2 cross-parent fix:全 row 各自掛 useDraggable/useDroppable(含 sub-rows;v15 無 SortableContext),
+  // custom collisionDetection 過濾掉 cross-parent over candidates,保留「同 parent siblings」。沒命中 → invalid drop signal。
   // parentMap: rowId → parentId(top-level row 的 parent = '' 哨兵 string)
   const { allRowIds, parentMap } = React.useMemo(() => {
     const ids: string[] = []
@@ -1362,13 +1587,13 @@ function DataTableInner<TData>(
       const rowId = cell.row.id
       const rowOriginal = cell.row.original
       const isDisabled = isRowSelectable ? !isRowSelectable(rowOriginal) : false
-      const ariaLabel = getRowAriaLabel?.(rowOriginal) ?? 'Select row'
+      const ariaLabel = getRowAriaLabel?.(rowOriginal) ?? '選取此列'
       const checkboxSize = size === 'lg' ? 'lg' : 'md'
       // Cell 整格可點:click cell padding 也觸發 toggle/select(對齊 Linear / Apple Mail / Material DataGrid)
       // 內部 checkbox/radio 用 stopPropagation 避免 double-fire
       const onCellClick = isDisabled ? undefined : (e: React.MouseEvent) => {
         e.stopPropagation()
-        if (mode === 'single') setSelection([rowId])
+        if (mode === 'single') setSelection({ mode: 'include', ids: [rowId] })
         else toggleRow(rowId, rowOriginal, { shiftKey: e.shiftKey })
       }
       return (
@@ -1395,7 +1620,7 @@ function DataTableInner<TData>(
           ) : (
             <Checkbox
               size={checkboxSize}
-              checked={selectionSet.has(rowId)}
+              checked={isSelectedId(rowId)}
               disabled={isDisabled}
               aria-label={ariaLabel}
               onClick={(e) => {
@@ -1423,17 +1648,15 @@ function DataTableInner<TData>(
     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)
-    // Indicator canonical(2026-05-09 D-path retire):**Field naked-display branch own** via
+    // Indicator canonical(2026-05-09 D-path retire):**Field naked-view branch own** via
     //   `showDisplayEndIcon` opt-in(per-picker `<ItemSuffix>` 渲 ChevronDown/Calendar/Clock)。
     //   DataTable cellEl 不再 render parallel indicator — SSOT 對齊 Field family。
     //   詳 `.claude/planning/cell-indicator-ssot-rfc.md` Step 9。
     // Cell click → 進 edit mode(boolean 不需 — 自己 toggle;url 不需 — 走內部 Pencil button,Phase C 由 UrlCell 內處理)
     const cellSpreadsheetId = `${cellRowId}:${cellColId}`
     const isSelectedCell = spreadsheetMode && selectedCellId === cellSpreadsheetId
-    // 2026-05-13 Q3:cellDisabled → 抑制 editable click(對齊 `editable && !disabled` invariant)
-    const onEditableCellClick = cellEditable && !cellDisabled && colType !== 'boolean' && colType !== 'url' && !isEditingThisCell
+    const onEditableCellClick = cellEditable && colType !== 'boolean' && colType !== 'url' && !isEditingThisCell
       ? (e: React.MouseEvent) => {
         if (spreadsheetMode) {
           // Slice D Step 4 spreadsheet semantics(2026-05-10 user 拍板,2026-05-12 v2 fix):
@@ -1477,7 +1700,13 @@ function DataTableInner<TData>(
     const canExpand = cell.row.getCanExpand?.() ?? false
     const isExpanded = cell.row.getIsExpanded?.() ?? false
     const toggleExpand = cell.row.getToggleExpandedHandler?.()
-    const showNestedPrefix = isFirstContent && (depth > 0 || canExpand)
+    // 2026-07-08 sibling-aware 佔位(WM root-cause 戰役):spec:382「同層 sibling 有 expandable
+    // 時 leaf 也佔位」原本沒實作 — depth-0 leaf(無 children 的頂層列)拿不到 w-4+mr-2 佔位,
+    // 與同層有 chevron 的列左緣錯位(PDF「chevron 空間」問題)。同層 = 同 parent 的 subRows;
+    // 頂層 = core rows。只在 isFirstContent 時計算,成本一列一次。
+    const siblingRows = cell.row.getParentRow?.()?.subRows ?? table.getCoreRowModel().rows
+    const siblingHasExpand = isFirstContent && siblingRows.some((r) => r.getCanExpand?.() ?? false)
+    const showNestedPrefix = isFirstContent && (depth > 0 || canExpand || siblingHasExpand)
     // Issue 9 cell error(2026-05-10):lookup `${rowId}:${colId}` in cellErrors map
     // editing cell 自動 clear visual error(per spec 「edit-clears-own-cell」)— consumer 走
     // onCellCommit 驗證後決定回填新 error(由 consumer 端控制 cellErrors map state)。
@@ -1503,7 +1732,7 @@ function DataTableInner<TData>(
         role="cell"
         // group/cell + data-row-mode:讓 Field naked 用 `group-data-[row-mode=...]/cell:items-X`
         // 從 cell 取 alignment(autoRowHeight=auto 頂對齊 / fixed=fixed 置中)。CSS propagation,
-        // Field API 不變;每個 mode 內 display↔edit 同 alignment(同 Field, 同 group → 同 items)。
+        // Field API 不變;每個 mode 內 view↔edit 同 alignment(同 Field, 同 group → 同 items)。
         // H1(2026-05-10):per-row error → effectiveAutoRowForCell 同 row.tsx effectiveAutoRow
         data-row-mode={effectiveAutoRowForCell ? 'auto' : 'fixed'}
         data-column-id={cell.column.id}
@@ -1513,8 +1742,6 @@ function DataTableInner<TData>(
         // Phase 9 Issue 1 fix(2026-05-10):range cell bg fill via CSS [data-range-cell],
         // 不在 overlay layer(避免 layer fixed-position bg 蓋 cell content)。
         data-range-cell={spreadsheetMode && rangeCellIdSet.has(`${cell.row.id}:${cell.column.id}`) ? '' : undefined}
-        // 2026-05-13 V1.6:data-cell-disabled attribute 給 CSS `:not([data-cell-disabled])` 過濾,disabled cell 不被 range fill 蓋
-        data-cell-disabled={cellDisabled ? 'true' : undefined}
         // Issue 9 cell error(2026-05-10):aria-describedby 接 error message id 給 AT 讀
         aria-describedby={cellErrorId}
         aria-invalid={hasCellError || undefined}
@@ -1529,7 +1756,11 @@ function DataTableInner<TData>(
           //     「框框跟 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 訊息可能多行
@@ -1541,22 +1772,24 @@ function DataTableInner<TData>(
           // 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',
+          onEditableCellClick && ['cursor-pointer', nakedCellEditableDisplayHover],  // 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」)。
@@ -1564,9 +1797,22 @@ function DataTableInner<TData>(
           ...(experimentalSpreadsheetOverlay && { '--cell-hover-outline-color': 'transparent' } as React.CSSProperties),
         }}
         onClick={onEditableCellClick}
+        // a11y(2026-07-14 dim-10 修):非 spreadsheet 的 inlineEdit cell 原本只有 onClick —
+        // 鍵盤 user 無法聚焦 cell、無法進入編輯(WCAG 2.1.1)。對齊 Atlassian InlineEdit
+        // read-view-focusable idiom:editable view cell 可 Tab 聚焦,Enter / F2 進 edit。
+        // spreadsheetMode 不加(該模式走 table-level selectedCellId 鍵盤導覽 SSOT,per-cell
+        // tab stop 會跟 roving 模型衝突);cell 內 embedded 控件事件不攔(target guard)。
+        tabIndex={onEditableCellClick && !spreadsheetMode ? 0 : undefined}
+        onKeyDown={onEditableCellClick && !spreadsheetMode ? (e) => {
+          if (e.target !== e.currentTarget) return
+          if (e.key === 'Enter' || e.key === 'F2') {
+            e.preventDefault()
+            setEditingCellId(cellEditId(cellRowId, cellColId))
+          }
+        } : undefined}
       >
         {/* Issue 9 cell error(2026-05-10):有 error → cell 內外結構切 flex-col,
-            上 row 渲既有 nested + content,下 row 渲 error message 14px text-error。
+            上 row 渲既有 nested + content,下 row 渲 error message `text-body text-error`。
             無 error 時走原 flex-row(backward-compat 0 layout shift)。 */}
         {hasCellError ? (
           <span className="flex flex-col self-stretch w-full min-w-0 gap-1">
@@ -1581,7 +1827,7 @@ function DataTableInner<TData>(
                       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)' : undefined }}
                       onClick={(e) => { e.stopPropagation(); toggleExpand?.() }}
                     >
@@ -1626,7 +1872,7 @@ function DataTableInner<TData>(
                     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)' : undefined }}
                     onClick={(e) => { e.stopPropagation(); toggleExpand?.() }}
                   >
@@ -1662,8 +1908,10 @@ function DataTableInner<TData>(
   React.useEffect(() => {
     if (!enabled || preserveSelectionOnFilter) return
     setSelection(prev => {
-      const filtered = prev.filter(id => visibleRowIdsSet.has(id))
-      return filtered.length === prev.length ? prev : filtered
+      // all 模式 = 「全部符合當前 filter」→ 不清(excluded 留著,被 filter 掉的 excluded 列無害)
+      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])
 
@@ -1675,9 +1923,22 @@ function DataTableInner<TData>(
       .map(r => r.id)
   }, [rows, enabled, isRowSelectable])
 
+  // Union-aware「某列是否選取」+ 計數(include = ids 內;all = 不在 excluded 內)
+  const includeSet = React.useMemo(
+    () => (selection.mode === 'include' ? new Set(selection.ids) : new Set<string>()),
+    [selection],
+  )
+  const excludeSet = React.useMemo(
+    () => (selection.mode === 'all' ? new Set(selection.excluded) : new Set<string>()),
+    [selection],
+  )
+  const isSelectedId = React.useCallback(
+    (id: string) => (selection.mode === 'include' ? includeSet.has(id) : !excludeSet.has(id)),
+    [selection.mode, includeSet, excludeSet],
+  )
+  const hasAnySelection = selection.mode === 'all' || includeSet.size > 0
   // Header tri-state checkbox value
-  const selectionSet = React.useMemo(() => new Set(selection), [selection])
-  const visibleSelectedCount = selectableVisibleIds.filter(id => selectionSet.has(id)).length
+  const visibleSelectedCount = selectableVisibleIds.filter(id => isSelectedId(id)).length
   const headerCheckedState: boolean | 'indeterminate' =
     selectableVisibleIds.length === 0 ? false
       : visibleSelectedCount === 0 ? false
@@ -1691,20 +1952,16 @@ function DataTableInner<TData>(
   )
 
   const toggleHeaderCheckbox = React.useCallback(() => {
-    if (headerCheckedState === true) {
-      // 清掉本頁可見已選(保留可見外的 selection)
-      const visibleSet = new Set(selectableVisibleIds)
-      setSelection(prev => prev.filter(id => !visibleSet.has(id)))
-    } else {
-      // 選全可見(扣除 disabled);保留可見外的既有 selection
-      setSelection(prev => Array.from(new Set([...prev, ...selectableVisibleIds])))
-    }
+    // header tri-state visible-scoped:全可見已選 → 取消可見;否則 → 選全可見。
+    // include / all 兩模型由 applySelectIds 處理(all 模式 toggle 改寫 excluded)。
+    const willSelect = headerCheckedState !== true
+    setSelection(prev => applySelectIds(prev, selectableVisibleIds, willSelect))
   }, [headerCheckedState, selectableVisibleIds, setSelection])
 
   const toggleRow = React.useCallback((rowId: string, rowOriginal: TData, opts?: { shiftKey?: boolean }) => {
     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
     }
@@ -1722,24 +1979,16 @@ function DataTableInner<TData>(
           return row && (!isRowSelectable || isRowSelectable(row.original))
         })
         // Mail / GitHub 慣例:shift-click 把 range 全變「rowId 點擊後該變的狀態」
-        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 willCheck = !isSelectedId(rowId)
+        setSelection(prev => applySelectIds(prev, rangeIds, willCheck))
         return
       }
     }
-    // 一般 toggle + 更新 anchor
-    setSelection(prev => {
-      const set = new Set(prev)
-      if (set.has(rowId)) set.delete(rowId)
-      else set.add(rowId)
-      return Array.from(set)
-    })
+    // 一般 toggle + 更新 anchor(include / all 由 applySelectIds 處理)
+    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])
 
   // ── Cmd+A / Esc / Arrow keys 鍵盤 handler(table-level)──
   // code-quality-allow: long-function — single keyboard dispatch covering Cmd+A / Esc / Arrow / Space + selection state mutations,拆 sub-handler 會切散 keyboard mode coherence
@@ -1752,7 +2001,33 @@ function DataTableInner<TData>(
       // Phase B3 IME guard(2026-05-10 per codex Q-B3):中文輸入法組字中 ignore 所有 nav keys。
       // 2026-05-16 Round 5 audit Dim 27 fix:`keyCode` deprecated but still in KeyboardEvent type — no cast needed。
       if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) return
-      if (spreadsheetMode && selectedCellId != null && editingCellId == null) {
+      // 2026-07-14 dim-10 修:spreadsheet 分支排除 descendant 互動控件 — 焦點在 cell 內
+      // action button / link / input 時,Enter 應 activate 該控件、方向鍵交還控件,
+      // 原 handler 會 preventDefault 取消按鈕 activation、拿舊 selectedCellId 導覽。
+      // 對齊下方 row-selection 分支 2026-07-09 既有 input-family guard + AG Grid
+      // embedded-control convention(cell renderer 內控件 own keyboard)。
+      const spreadsheetKbTarget = e.target as HTMLElement | null
+      const targetIsEmbeddedControl = !!spreadsheetKbTarget?.closest?.(
+        'button, a[href], input, select, textarea, [contenteditable="true"]',
+      )
+      // 2026-07-05 D4 fix:spreadsheet 鍵盤入口 — selection 尚未建立時按方向鍵,seed 第一個
+      // visible cell(原本唯一 set 起點是 mouse click → 鍵盤-only 使用者 Tab 進 table 後方向鍵
+      // 全 no-op,整個 spreadsheet 導覽被滑鼠 gate,違反 spec「鍵盤完整可操作」驗證宣稱。
+      // 對齊 Excel / Google Sheets / AG Grid「focus grid → first cell active」canonical)。
+      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(':')
@@ -1770,8 +2045,7 @@ function DataTableInner<TData>(
         else if (e.key === 'ArrowLeft' && curColIdx > 0) { nextColIdx = curColIdx - 1 }
         else if (e.key === 'ArrowRight' && curColIdx < allCols.length - 1) { nextColIdx = curColIdx + 1 }
         else if (e.key === 'Enter' || e.key === 'F2') {
-          // Enter / F2 → 進 edit(若 cell editable + 非 boolean / url + 非 disabled)
-          // 2026-05-13 codex V1 fix:加 `!isCellDisabled(meta, row)` gate(對齊 mouse click invariant)
+          // Enter / F2 → 進 edit(若 cell editable + 非 boolean / url)。edit 入口統一走 canEditCell(= isCellEditable)。
           const row = table.getRowModel().rowsById[curRowId]
           const colDef = table.getAllLeafColumns().find((c) => c.id === curColId)
           // any-allow: column meta free-form
@@ -1803,22 +2077,33 @@ function DataTableInner<TData>(
       }
       // ── Row selection mode keyboard handler(下方既有)──
       if (!enabled) return
+      // 2026-07-09 fix(圖一 Ctrl+A bug):焦點在可編輯輸入元素(cell edit / inline edit / 搜尋框)時,
+      // 鍵盤(Cmd/Ctrl+A 全選、Esc)應交給該元素(全選 cell 文字 / 取消編輯),**不**攔成 row selection。
+      // 對齊 Notion / Airtable / Linear:編輯格內 Ctrl+A = 選格內文字,非選全表列。
+      const kbTarget = e.target as HTMLElement | null
+      if (
+        editingCellId != null ||
+        (kbTarget && (kbTarget.tagName === 'INPUT' || kbTarget.tagName === 'TEXTAREA' || kbTarget.tagName === 'SELECT' || kbTarget.isContentEditable))
+      ) return
       // Cmd/Ctrl+A:選全可見(扣 disabled)— 對齊 Mail / GitHub / Linear 慣例
       if ((e.metaKey || e.ctrlKey) && e.key === 'a' && mode === 'multi') {
         e.preventDefault()
-        setSelection(prev => Array.from(new Set([...prev, ...selectableVisibleIds])))
+        setSelection(prev => applySelectIds(prev, selectableVisibleIds, true))
         return
       }
       // Esc:clear selection
-      if (e.key === 'Escape' && selection.length > 0) {
+      if (e.key === 'Escape' && hasAnySelection) {
         e.preventDefault()
-        setSelection([])
+        setSelection({ mode: 'include', ids: [] })
         anchorRowIdRef.current = null
         return
       }
     },
-    [enabled, mode, selection.length, selectableVisibleIds, setSelection,
-     spreadsheetMode, selectedCellId, editingCellId, table, isCellEditable]
+    // 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, hasAnySelection, selectableVisibleIds, setSelection,
+     spreadsheetMode, selectedCellId, editingCellId, table, canEditCell]
   )
 
   // ── Header cell ──
@@ -1841,7 +2126,7 @@ function DataTableInner<TData>(
               checked={headerCheckedState}
               onClick={(e) => e.stopPropagation()}
               onCheckedChange={() => toggleHeaderCheckbox()}
-              aria-label="Select all visible rows"
+              aria-label="全選可見列"
               disabled={selectableVisibleIds.length === 0}
             />
           )}
@@ -1875,7 +2160,10 @@ function DataTableInner<TData>(
           // 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',
         )}
@@ -1891,17 +2179,22 @@ function DataTableInner<TData>(
           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',
           )}
         >
-          <TruncateCell className={cn('min-w-0', align === 'right' && 'text-right', align === 'center' && 'text-center')}>
+          <TruncatedText className={cn('min-w-0', align === 'right' && 'text-right', align === 'center' && 'text-center')}>
             {header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext())}
-          </TruncateCell>
+          </TruncatedText>
           {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 變。
-            <SortIcon size={ICON_SIZE[size]} aria-hidden 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 顏色列。
+            <SortIcon size={ICON_SIZE[size]} aria-hidden className="shrink-0" />
           )}
         </div>
         {/* 右區:⌄ menu(hover/focus-within 才顯;**不顯示時不佔位**)
@@ -1985,16 +2278,40 @@ function DataTableInner<TData>(
           const colOptIn = colMeta?.resizable !== false
           const isResizable = enableColumnResize && !isSystemColumn(colId) && colOptIn
           const isResizing = header.column.getIsResizing?.()
+          // 鍵盤 resize(WAI-ARIA window-splitter):方向鍵調整欄寬,公開目前值 + 下限。
+          // effectiveMinWidth 對齊 drag 路徑(resolveColumnSizing minSize),step 16px。
+          const effectiveMinWidth = header.column.columnDef.minSize ?? MIN_COLUMN_WIDTH
+          const currentWidth = Math.round(header.column.getSize())
+          const RESIZE_KEY_STEP = 16
           // H2: 不論 showDivider,只要 isResizable 就 render hot zone(panel boundary col 仍可拖)
           if (!showDivider && !isResizable) return null
           return (
             <span
               role={isResizable ? 'separator' : undefined}
               aria-orientation={isResizable ? 'vertical' : undefined}
-              aria-label={isResizable ? '拖曳調整欄寬' : undefined}
+              aria-label={isResizable ? '調整欄寬' : undefined}
+              // 鍵盤可操作 separator(WAI-ARIA window-splitter):focusable + 方向鍵調整 +
+              // 公開目前寬度 / 下限。aria-valuetext 給 SR px 值(避免無 valuemax 時被誤讀成百分比)。
+              tabIndex={isResizable ? 0 : undefined}
+              aria-valuenow={isResizable ? currentWidth : undefined}
+              aria-valuemin={isResizable ? effectiveMinWidth : undefined}
+              aria-valuetext={isResizable ? `${currentWidth}px` : undefined}
+              onKeyDown={isResizable ? (e: React.KeyboardEvent<HTMLSpanElement>) => {
+                let next: number | null = 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
+                // stopPropagation:不讓方向鍵冒泡到 header 排序 / 欄位拖曳 keyboard listener。
+                e.preventDefault()
+                e.stopPropagation()
+                table.setColumnSizing((prev) => ({ ...prev, [colId]: next as number }))
+                // onColumnResize 由 columnSizing useEffect 自動 fire(非 drag 路徑不經 isResizingColumn)。
+              } : undefined}
               className={cn(
                 'group/resize absolute top-0 bottom-0 right-0 -mr-[3px] w-[7px]',
                 isResizable && 'cursor-col-resize select-none',
+                isResizable && 'focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring',
               )}
               // 2026-05-12 fix v2(user 抓 R3 stopPropagation 沒生效):dnd-kit PointerSensor
               // 監聽 `pointerdown`,我前一輪只 stop `onMouseDown` → pointerdown 仍冒泡 →
@@ -2054,6 +2371,18 @@ function DataTableInner<TData>(
   // 2026-05-06 v14.4 Notion blue line drop indicator(column reorder visual canonical)
   // 必須宣告在 renderHeaderRow 之前(closure 引用,避 minified bundler TDZ false-positive)
   const [dropIndicator, setDropIndicator] = React.useState<{ id: string; side: 'before' | 'after'; type: 'row' | 'column' } | null>(null)
+  // 2026-07-05 D3 perf fix:shallow-compare setter — drag 中每次 over 變更 handleDragOver 都
+  // set 全新 object,即使 id/side/type 沒變也觸發整個 DataTableInner 重渲(全 visible rows +
+  // cells + header)。值相同 → 回傳 prev reference 讓 React bail out(對齊檔內 invalidRef guard
+  // pattern;`setDropIndicator(null)` 自帶 Object.is bail out 不需經此)。
+  const setDropIndicatorIfChanged = React.useCallback(
+    (next: { id: string; side: 'before' | 'after'; type: 'row' | 'column' }) => {
+      setDropIndicator((prev) =>
+        prev && prev.id === next.id && prev.side === next.side && prev.type === next.type ? prev : next,
+      )
+    },
+    [],
+  )
   // ref for stable lookup in handleDragOver(避免 closure 抓舊值)
   const reorderableColumnIdsRef = React.useRef<string[]>([])
 
@@ -2074,7 +2403,7 @@ function DataTableInner<TData>(
           const meta = h.column.columnDef.meta as { locked?: boolean } | undefined
           const isLocked = meta?.locked === true
           const isSystem = isSystemColumn(colId)
-          // useSortable per header(Rules of Hooks compliant — same hook count per render
+          // useDraggable + useDroppable per header(Rules of Hooks compliant — same hook count per render
           // as long as headers count consistent;column reorder/hide 整 row reflow 自然觸發 React reconcile)。
           // disabled=true 時仍 call hook 不啟動 listeners。
           const isDraggable = enableColumnReorder && !isLocked && !isSystem
@@ -2124,13 +2453,13 @@ function DataTableInner<TData>(
     const isPrimaryRegion = isCenter
     const regionRole: 'primary' | 'mirror' = isPrimaryRegion ? 'primary' : 'mirror'
 
-    // code-quality-allow: long-function — virtualizer × sticky panel × drag listeners × hover delegation × per-row state 多 closure capture;拆會破壞 SortableContext / dnd-kit hooks 跟 row idx 的 stable binding
+    // code-quality-allow: long-function — virtualizer × sticky panel × drag listeners × hover delegation × per-row state 多 closure capture;拆會破壞 dnd-kit hooks 跟 row idx 的 stable binding
     const rowEl = (row: typeof rows[number], idx: number, opts?: { virtual?: boolean; start?: number; isLast?: boolean }) => {
       const showBorder = bordered !== false ? !opts?.isLast : true
-      // L4 row drag v2:nested rows 也 sortable(配合 cross-parent collisionDetection 過濾)
-      // sub-rows: depth>0 仍進 SortableContext,但 collisionDetection 只接受 same-parent over
+      // L4 row drag v2:nested rows 也可拖(配合 cross-parent collisionDetection 過濾)
+      // sub-rows: depth>0 也各自掛 useDraggable/useDroppable,但 collisionDetection 只接受 same-parent over
       const isThisRowDragging = enableRowDrag && activeDragId === row.id
-      const useSortableWrap = enableRowDrag
+      const dragRowWrap = enableRowDrag
 
       // H1 fix(2026-05-10,per user 確認):per-row autoRowHeight when any cell in this row has
       // error。Fixed-height row 模式下,該 row 的任一 cell 有 error msg → THAT row 自動 auto-height
@@ -2145,8 +2474,9 @@ function DataTableInner<TData>(
       const effectiveAutoRow = autoRowHeight || rowHasError
 
       // L4 row drag:handle absolute 貼齊 row 左 border(Jira canonical),不佔 column 空間。
-      // 只在 primary region(left 若有,否則 center)+ depth===0 render — RowDragHandle
-      // 內部再用 ctx.role === 'primary' 守門避免 mirror region 重複 render。
+      // 只在 primary region + depth===0 render — primary 永遠 = center(v15.4 撤銷「left 優先」,
+      // 見上方 isPrimaryRegion 註解);RowDragHandle 內部再用 ctx.role === 'primary' 守門避免
+      // mirror region 重複 render。
       const showDragHandle = enableRowDrag && (row.depth ?? 0) === 0 && isPrimaryRegion
       // v15.2 SSOT 對齊 TreeView:drag 期間 suppress 全表 hover state
       // (user directive「drag 時 row 不應 hover / drag button 不應出現」)
@@ -2184,7 +2514,10 @@ function DataTableInner<TData>(
           // 找 source row(避免 multi-region 場景挑錯 region 的 row 當 ghost)
           data-row-drag-source={enableRowDrag && isPrimaryRegion ? 'true' : undefined}
           role="row"
-          aria-rowindex={idx + 2}
+          // L5 分頁(2026-07-07 C13):rowindex 加分頁 offset — aria-rowcount 是全集,
+          // 第 2 頁起 index 必須接續(否則 AT 讀到「第 129 列中的第 2 列」錯位);
+          // 不可用 row.index(sort/filter 後是原始資料序,非視覺序)
+          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
@@ -2228,20 +2561,20 @@ function DataTableInner<TData>(
         </div>
       )
 
-      if (useSortableWrap) {
+      if (dragRowWrap) {
         // invalidDrop 只對「正在被拖」的 row 顯示 — handle 在 active row 上,UI 警示只需該 row
-        // code-quality-allow: long-function — 此 const 之下的整個 if-block 含 useSortable hooks + SortableRowProvider + baseRowDiv composition;audit 把 const 誤認為 function entry,實 long body 在 closure 內 dnd-kit + per-row state 多 capture,拆會破壞 hook order invariant
+        // code-quality-allow: long-function — 此 const 之下的整個 if-block 含 dnd-kit hooks + SortableRowProvider + baseRowDiv composition;audit 把 const 誤認為 function entry,實 long body 在 closure 內 dnd-kit + per-row state 多 capture,拆會破壞 hook order invariant
         const rowInvalidDrop = isThisRowDragging && invalidDropActive
         return (
           <SortableRowProvider key={row.id} id={row.id} disabled={dragDisabled} role={regionRole} invalidDrop={rowInvalidDrop}>
             {(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,
             })}
@@ -2302,7 +2635,8 @@ function DataTableInner<TData>(
       // 行為:**永遠 hug rows**,只在被約束時才 cap + body shrink + V scroll。
       // 簡單需求:有約束 → rows 沒超就 hug;超就 cap+scroll;RWD 同理。
       style={isFillHeight ? { maxHeight: height } : undefined}
-      role="table" aria-rowcount={rows.length + 1}
+      // L5 分頁:aria-rowcount = 全集筆數非當頁(ARIA 規範;getPrePaginationRowModel = filter 後全集)
+      role="table" aria-rowcount={(paginationEnabled ? table.getPrePaginationRowModel().rows.length : rows.length) + 1}
       // Phase 9 Issue 12 fix(2026-05-10 codex 抓):**single tabIndex prop**,合併 selection
       // 跟 spreadsheet 兩 path。React 在 dup props 只 keep last 是 silent regression risk。
       tabIndex={enabled || spreadsheetMode ? 0 : undefined}
@@ -2321,10 +2655,10 @@ function DataTableInner<TData>(
         )}
         {/* Header 的 center 區保持 overflow-hidden(非 scroll)—— body 的 center 才有 scroll,
             header 靠 JS 同步 scrollLeft(見 onCenterBodyScroll)。這樣不會出現雙 scrollbar。
-            為了對齊 body 的 V scrollbar(native 捲軸吃 ~15-17px 寬),header 等寬預留 gutter:
-            `scrollbar-gutter: stable` 放在 centerBody(真正有 V scroll 的 container)+
-            header 這層不需額外處理,因為 body 預留了空間後 H 內容寬度會自然等同 header。
-            注意:header 的 `scrollbar-gutter` 無效(因為 overflow-hidden),刻意不設 */}
+            V scrollbar 對齊:centerBody **刻意不用** `scrollbar-gutter: stable`(決策見 centerBody
+            className 註解 — 永久預留 15px 會讓 content-fit 看起來像恆有 V 捲軸);trade-off =
+            V scroll 出現時 body 內側少 ~15px、header 不縮 → 右端微 misalign,content-fit 乾淨優先。
+            header 的 `scrollbar-gutter` 本就無效(overflow-hidden),刻意不設 */}
         <div
           ref={centerHeaderRef}
           data-datatable-header-panel="center"
@@ -2372,16 +2706,28 @@ function DataTableInner<TData>(
         <div
           ref={centerBodyRef}
           // Center body 同時擁有 H + V scroll;maxHeight 限制讓 H scrollbar 落在 visible 底部
-          // `scrollbar-gutter: stable` 永遠預留 V scrollbar 寬度(~15-17px),避免 body 出現 V
-          // scrollbar 時右端被縮,跟 header 右端產生 gap(Windows/Linux native scrollbar 吃寬)
           data-datatable-hscroll
           data-datatable-panel="center"
+          // a11y(scrollable-region-focusable,對齊 DS ScrollArea Viewport canonical):唯讀表格
+          // 的可捲動 body 若無任何 focusable descendant,鍵盤使用者無法捲動。read-only 模式
+          // (非 enabled / spreadsheet)outer table 也不 focusable → 這裡補 tabIndex=0 + 具名 +
+          // inset focus ring,讓鍵盤可聚焦後方向鍵捲動;互動模式已由 outer table keyboard handler
+          // + focusable cells 覆蓋,不重複加 tab stop。
+          // **role="rowgroup" 必要**(2026-07-29 WM beta.95 axe 錨例):focusable 的無 role
+          // 中間層會被 axe aria-required-children 視為 role="table" 的不合法 owned child,
+          // 打斷 table→row ownership(修 scrollable-region-focusable 反引爆 required-children,
+          // 與 Tabs 2026-07-18 決策1 同型)。rowgroup = W3C ARIA 1.2 合法 table 子代 + 可具名
+          // (Name from author §5.2.8.4)+ 容納 rows,兩規則唯一同時滿足解。
+          // 空表例外:Empty 塊非 row → 不掛 rowgroup;空表無 overflow 也無需 tabIndex/名稱。
+          role={isEmpty ? undefined : 'rowgroup'}
+          tabIndex={enabled || spreadsheetMode || isEmpty ? undefined : 0}
+          aria-label={enabled || spreadsheetMode || isEmpty ? undefined : '表格內容,可捲動'}
           // overflow-x/y: auto — 沒 overflow 就不顯 bar。wrapper minWidth 仍 trigger H 真 overflow。
           // **不**用 scrollbar-gutter: stable — 那會永遠保留 V 軸 15px 空間,
           // content fit 時看起來像「永遠有 V 捲軸」(Image #5 bug)。
           // trade-off:V scroll 出現時 body 內側少 15px,header 不縮 → 右端微 misalign,
           // 但 content fit 視覺乾淨優先(Mac 用戶 overlay scrollbar 不可見)。
-          className="flex-1 min-w-0 overflow-x-auto overflow-y-auto"
+          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"
           // isFillHeight:用 JS 算的 px(bodyMaxHeight),bypass CSS % 在 flex 場景的不可靠 shrink。
           // 固定 px(300px etc):直接套 height。
           style={
@@ -2434,7 +2780,7 @@ function DataTableInner<TData>(
         activeEditorEnabled={experimentalActiveEditorController}
         // Slice D Step 5(D.3 portal Field,2026-05-10):real portal Field render callback。
         // Layer 在 ActiveEditorHost(z 3 float rect)render `<Cell mode="edit" />` 同 registry。
-        // Cell wrapper 保持 mode="display"(SSOT preserved per codex Q6.2)。
+        // Cell wrapper 保持 mode="view"(SSOT preserved per codex Q6.2)。
         activeEditorRender={experimentalActiveEditorController ? (cellId) => {
           const lastColon = cellId.lastIndexOf(':')
           if (lastColon < 0) return null
@@ -2505,12 +2851,25 @@ function DataTableInner<TData>(
               // 2026-05-13:canEditCell helper(per V4 consolidation,合 editable + !disabled invariant)
               if (!nextRow || !canEditCell(nextMeta, nextRow.original)) continue
               // 找到 next editable cell → commit current + start next edit
+              // 2026-07-05 D4 fix:原本只 setEditingCellId —(a)同 type 相鄰 cell React 同位
+              // 重用 input DOM,blur 不 fire → onBlur commit 不觸發,剛打的 draft 整段遺失;
+              // (b)editingDraft 不清 → 下一格 portal value 顯示上一格草稿(甚至把上一格 draft
+              // commit 進錯的 cell)。Fix:有 draft 先 commit 當前 cell(commitCell 內已清 draft),
+              // 再換格;spreadsheet selection 對齊 edit-entry canonical 清空(commitCell 的
+              // selection restore 對 Tab 換格不適用 — 下一格馬上進 edit)。
+              if (editingDraft !== undefined) commitCell(rowId, colId, editingDraft)
               setEditingCellId(cellEditId(allRows[nextRowIdx], allCols[nextColIdx]))
+              setSelectedCellId(null)
+              setRangeAnchor(null)
+              setRangeFocus(null)
               return
             }
           }
           return (
-            <div onKeyDownCapture={handleEditTab} style={{ width: '100%', height: '100%' }}>
+            // 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)。
+            <div key={cellId} onKeyDownCapture={handleEditTab} style={{ width: '100%', height: '100%' }}>
               <Cell
                 value={value}
                 meta={meta}
@@ -2520,19 +2879,18 @@ function DataTableInner<TData>(
                 isEditable={cellEditable}
                 onCommit={(next) => commitCell(rowId, colId, next)}
                 onCommitLive={(next) => onCellCommit?.(rowId, colId, next)}
-                onCancel={exitEdit}
+                onCancel={() => cancelCellEdit(rowId, colId)}  // 2026-07-05 D4:cancel 還原 selection(Contract 11)
                 onDraft={setEditingDraft}  // Phase 7:每 keystroke 寫 draft → preserve across virtualizer unmount
               />
             </div>
           )
         } : undefined}
-        // Slice D Step 4 spreadsheet semantics(2026-05-10):
-        //   selectedCellId(click 1)= solid border SelectionRect z 2
-        //   rangeCellIds(Shift+click rectangle from anchor↔focus)= cell-bg fill via
-        //     CSS `[data-range-cell]`(per Issue 1 codex verdict;layer 不畫 fill,只畫
-        //     RangeOuterRing 4 line div boundary)
+        // Slice D Step 4 spreadsheet semantics(2026-05-10;2026-07-14 對齊清理):
+        //   selectedCellId(click 1)= solid border SelectionRing z 2
+        //   range(Shift+click rectangle from anchor↔focus)= cell-bg fill via
+        //     CSS `[data-range-cell]`(per Issue 1 codex verdict;layer 不畫 range 視覺,
+        //     RangeOuterRing / rangeCellIds prop 已 retire)
         selectedCellId={spreadsheetMode ? selectedCellId : null}
-        rangeCellIds={rangeCellIds}
         cellClickEntersEdit={(cellId) => {
           // 2026-05-10 codex review red light fix(per dual-track verify):
           //   1. cellId parse 用 lastIndexOf(':')(row id 可含 colon)
@@ -2561,14 +2919,14 @@ function DataTableInner<TData>(
 
   // ── L4 Row drag DnD wrapper ───────────────────────────────────────────────
   // Sensors:Pointer(8px activation distance,避免 cell click 誤觸 drag)+ Keyboard(a11y)
-  // SortableContext items:**只 top-level row id**(nested sub-rows 不在 sortable 集合);
-  // 同 parent level 限制由「sub-rows 不在 items 內」自然成立。
+  // v15.0 Path B:無 SortableContext — 每 row 各自 useDraggable / useDroppable;
+  // 同 parent level 限制由自訂 collisionDetection 過濾 cross-parent target 成立(cross-parent over → invalidDrop)。
   // DragEnd:active.id / over.id → 算 position(active vs over 視覺位置),呼叫 onRowReorder。
   // hooks 必呼叫(rules-of-hooks)— 即使 enableRowDrag=false 也走 useSensors;wrap 才條件化。
   // **codex P1 fix(2026-05-07 v15.13)**:KeyboardSensor 不傳 `coordinateGetter`,用
   // dnd-kit 預設 25px 箭頭 stepping。`sortableKeyboardCoordinates` 是 `@dnd-kit/sortable`
   // preset,需 `<SortableContext>` 才正確 resolve 下一個 sortable target — 但 v15.0
-  // path B 已 explicit 砍 SortableContext 改用 useDraggable+useDroppable(line 21),
+  // path B 已 explicit 砍 SortableContext 改用 useDraggable+useDroppable(見檔頭 import 註解),
   // 此 getter 在無 context 下 keyboard nav 無法 reliable resolve target → keyboard
   // drag/reorder regression。Default getter(arrow-key Δ25px)在 useDraggable 場景是
   // dnd-kit canonical(`@dnd-kit/core/src/sensors/keyboard/defaults.ts` 預設行為)。
@@ -2584,7 +2942,7 @@ function DataTableInner<TData>(
   // pointerWithin 要求 pointer 真在 droppable rect 內才返回 → release 在 gap 自然 over=null →
   // 不觸發 reorder → snap back 自然成立(對齊 Notion / TreeView 行為)。
   // rectIntersection fallback 給 keyboard sensor(無 pointer)。
-  // 詳 .claude/references/drag-canonical.md。
+  // 詳 packages/design-system/ds-canonical/references/drag-canonical.md。
   const sameParentCollisionDetection: CollisionDetection = React.useCallback((args) => {
     const activeId = args.active?.id != null ? String(args.active.id) : null
     if (!activeId) {
@@ -2731,7 +3089,7 @@ function DataTableInner<TData>(
       const side: 'before' | 'after' = activeIdx < overIdx ? 'after' : 'before'
       // **v15.3 noop suppress**:drop position 等同原位 → 不顯 indicator(對齊 handleDragEnd noop guard)
       if (isReorderNoop(activeIdx, overIdx, side)) { setDropIndicator(null); return }
-      setDropIndicator({ id: String(over.id), side, type: 'column' })
+      setDropIndicatorIfChanged({ id: String(over.id), side, type: 'column' })
     } else {
       // Row drag — 用 allRowIds 算位置(只 same-parent siblings,跨 parent collisionDetection 已過濾)
       const activeIdx = allRowIds.indexOf(String(active.id))
@@ -2739,9 +3097,9 @@ function DataTableInner<TData>(
       if (activeIdx === -1 || overIdx === -1) { setDropIndicator(null); return }
       const side: 'before' | 'after' = activeIdx < overIdx ? 'after' : 'before'
       if (isReorderNoop(activeIdx, overIdx, side)) { 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)
@@ -2765,8 +3123,11 @@ function DataTableInner<TData>(
         const meta = table.getColumn(id)?.columnDef.meta as { locked?: boolean } | undefined
         return !meta?.locked
       })
+    // D3 dep-hygiene fix(2026-07-06):補 columnVisibility — memo 讀 table.getVisibleLeafColumns()
+    // (live,受 visibility 影響)原 deps 漏列,隱藏欄位後清單 stale(隱藏欄仍在 reorderable
+    // 列表 → handleDragOver 的 drop side 計算錯位)。
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [table, columnsWithSelection, tableOptions?.state?.columnOrder])
+  }, [table, columnsWithSelection, tableOptions?.state?.columnOrder, columnVisibility])
   // Sync ref(handleDragOver closure 抓不到最新 reorderableColumnIds)
   React.useEffect(() => { reorderableColumnIdsRef.current = reorderableColumnIds }, [reorderableColumnIds])
 
@@ -2840,6 +3201,43 @@ function DataTableInner<TData>(
     return sameParentCollisionDetection(args)
   }, [sameParentCollisionDetection])
 
+  // ── L5 分頁列(2026-07-06,詳 data-table.spec.md「L5:分頁」段)────────────────
+  // 間距 tight = layoutSpace spec 規則 3「跨範疇 functional 交互」;頁碼靠右(shadcn justify-end /
+  // Ant Table bottomEnd / MUI / Carbon 4 家實證,左側空也靠右);「共 N 筆」數源 = filter 後全集
+  // getPrePaginationRowModel(≠ selection all-mode 的 server-side 全集數 M — consumer 自持,語意不同)。
+  // 2026-07-06 user 拍板:「Pagination 元件本身提供完整功能(showTotal / 每頁筆數)= SSOT,
+  // Table 按一致定義套用」—— 分頁列的資訊/選單/「資訊左、操作右」layout 全部 own 在
+  // <Pagination> 完整形態;DataTable 只轉發 config + own TanStack state(controlled 消費:
+  // page/pageSize 狀態在本層、定義在 Pagination)。
+  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)。
+    <div ref={paginationBarRef} className="flex justify-end">
+      <Pagination
+        total={totalRowCount}
+        page={currentPage}
+        onPageChange={setCurrentPage}
+        pageSize={pageSizeState}
+        onPageSizeChange={(next) => {
+          setPageSizeState(next)
+          paginationOpts?.onPageSizeChange?.(next)
+        }}
+        showTotal={paginationOpts?.showTotal}
+        pageSizeOptions={paginationOpts?.pageSizeOptions}
+      />
+    </div>
+  ) : null
+  // isFillHeight 並用:外層接管高度(h-full min-h-0),tableContent 的 maxHeight cap 在內層照常生效
+  const composedContent = paginationBar ? (
+    <div className={cn('flex flex-col gap-[var(--layout-space-tight)]', isFillHeight && 'h-full min-h-0')}>
+      {tableContent}
+      {paginationBar}
+    </div>
+  ) : tableContent
+
   const wrapWithDnd = (node: React.ReactNode): React.ReactNode => {
     if (!enableRowDrag && !enableColumnReorder) return node
     return (
@@ -2886,14 +3284,14 @@ function DataTableInner<TData>(
   if (enabled && mode === 'single') {
     return (
       <RadioGroupPrimitive.Root
-        value={selection[0] ?? ''}
-        onValueChange={(v) => v && setSelection([v])}
+        value={selection.mode === 'include' ? (selection.ids[0] ?? '') : ''}
+        onValueChange={(v) => v && setSelection({ mode: 'include', ids: [v] })}
       >
-        {wrapWithDnd(tableContent)}
+        {wrapWithDnd(composedContent)}
       </RadioGroupPrimitive.Root>
     )
   }
-  return wrapWithDnd(tableContent)
+  return wrapWithDnd(composedContent)
 }
 
 export const DataTable = React.forwardRef(DataTableInner) as <TData>(
@@ -2913,7 +3311,9 @@ export const dataTableMeta = {
   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'],