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

package/src/components/DataTable/data-table.spec.md

@@ -19,19 +19,15 @@ benchmark:
 
 ## 定位
 
-DataTable 是基於 TanStack Table 的資料表格元件，提供排序、篩選、選取、欄位操作、虛擬捲動等完整能力。
-TanStack Table 負責邏輯，DataTable 負責視覺與互動。
+DataTable 是基於 TanStack Table 的資料表格元件，提供排序、篩選、選取、欄位操作、虛擬捲動等完整能力。TanStack Table 負責邏輯，DataTable 負責視覺與互動。
 
-簡單展示場景也用 DataTable（最少 config），不另外維護靜態 Table。
 底層使用 `<div>` + ARIA role，不用語義 `<table>`——虛擬捲動需要絕對定位 row，且未來 frozen column 需要獨立 scroll 區域，`<table>` 的佈局模型兩者都不支援。
 
-**預設不是試算表**——預設模式不做公式計算、不做跨 cell 選取(定位是「資料展示 + row 操作」,非 Excel)。但提供 **opt-in `spreadsheetMode` prop**:啟用後支援方向鍵跨 cell 導覽 + cell editing(見「鍵盤」段 L504-507),給確實需要 Excel-like 編輯的 productivity 場景。預設關閉以保持單純。(2026-06-01:原定位「不是試算表」與已 ship 的 `spreadsheetMode` opt-in 自相矛盾,改為「預設不是 + 可 opt-in」對齊 code;user 拍板保留功能)
+**預設不是試算表**——預設模式不做公式計算、不做跨 cell 選取(定位是「資料展示 + row 操作」,非 Excel)。但提供 **opt-in `spreadsheetMode` prop**:啟用後支援方向鍵跨 cell 導覽 + cell editing(見「A11y 預設」Keyboard 行為段),給確實需要 Excel-like 編輯的 productivity 場景。預設關閉以保持單純。(2026-06-01 user 拍板:原「不是試算表」與已 ship 的 opt-in 矛盾,改「預設不是 + 可 opt-in」對齊 code、保留功能)
 
 **Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
 
-### 檔案結構
-
-檔案拆分架構(12 file split matrix)與工程決策史屬 code home — 詳 `data-table.tsx` 檔頭 docblock(2026-06-11 遷移,Level 4;spec 只管設計語言)。
+**檔案結構**:檔案拆分架構(12 file split matrix)與工程決策史屬 code home — 詳 `data-table.tsx` 檔頭 docblock(2026-06-11 遷移,Level 4;spec 只管設計語言)。
 
 ---
 
@@ -56,9 +52,7 @@ TanStack Table 負責邏輯，DataTable 負責視覺與互動。
 
 ---
 
-## 層級架構
-
-每一層建立在前一層之上,可獨立啟用。
+## 層級架構(每一層建立在前一層之上,可獨立啟用)
 
 | 層級 | 能力 | 狀態 |
 |------|------|------|
@@ -66,7 +60,7 @@ TanStack Table 負責邏輯，DataTable 負責視覺與互動。
 | **L2 選取** | row selection、checkbox、單/多選、bulk action 整合 | ✅ 完成(本文件 L2 段)|
 | **L3 欄位互動** | 排序(本文件 L3)、resize、reorder、pin、顯示隱藏 | ✅ 完成(sort + resize + reorder + pin + visibility 全 props 支援:`enableColumnResize` / `enableColumnReorder` / `columnVisibility` / `pinnedLeftColumns` / `pinnedRightColumns`,見 `data-table.tsx` `DataTableProps` 宣告)|
 | **L4 資料操作 + Cell 能力** | 進階篩選(本文件 L4 Filter)、inline edit、nested rows、row drag(本文件 L4 段)| ✅ Filter / Inline edit / Nested rows / Row drag v3 完成(Jira canonical + virtualization fix) |
-| **L5 進階** | 分組、搜尋、tree data v2 enhancements、export CSV/Excel | 待 v2 |
+| **L5 進階** | **分頁(本文件 L5 段)**、分組、搜尋、tree data v2 enhancements、export CSV/Excel | ✅ 分頁完成(2026-07-06);其餘待 v2 |
 
 ---
 
@@ -74,45 +68,26 @@ TanStack Table 負責邏輯，DataTable 負責視覺與互動。
 
 ### 一、Table Size
 
-DataTable 有三種尺寸（`sm`、`md`、`lg`），透過 `size` prop 控制。
-
-**Size 不等於 density。** Size 是這張表格的結構決策（需要多緊湊），density 是全域的使用者偏好。同一頁可以有不同 size 的表格，density 全頁一致。
+DataTable 有三種尺寸（`sm`、`md`、`lg`），透過 `size` prop 控制。**Size 不等於 density。** Size 是這張表格的結構決策（需要多緊湊），density 是全域的使用者偏好。同一頁可以有不同 size 的表格，density 全頁一致。
 
 水平 padding 固定,不隨 size 或 density 變化(具體 token 見 `data-table.tsx`);垂直方向由行高模式決定(見第四節)。
 
 **Cell / header 字級隨 size,對齊 Field family。** 三種 size 的 cell 與 header 預設字級**必與同 size 的 Field 一致**:`sm`/`md` → `text-body`(14px)、`lg` → `text-body-lg`(16px),SSOT = `fieldDisplayTextClass()`(`field-wrapper.tsx`)。`lg` 行高放大時字級同步放大,避免「字小、行高大」失衡。**機制**:typed cell 由各自 Field 控件吃 `size` 自動套用(cell-registry 各 cell display mode 必傳 `size`,**禁漏傳**否則 fallback md 卡 14px);header 與非-Field 內容(consumer 自訂 cell)由 cell wrapper / header `cn(fieldDisplayTextClass(size))` 套用。`1lh`-based cell-py 公式(見第四節)隨字級自動吸收,row 高不變。
 
-### 二、高度模式
-
-**有高度約束 vs 無高度約束，決定可用的功能組合。**
-
-**有高度約束**(指定高度值,或父容器提供高度限制)
-- 行為:資料少→outer 內容高度;資料多→撐到上限後內部 scroll(虛擬捲動啟用,header 固定)
-- 高度來源:固定 `height="400px"` 等具體 px/rem,或 `height="100%"` 由父 flex 提供約束(Linear 做法)— 都走相同 cap 行為,無 dead surface
+### 二、高度模式(有高度約束 vs 無高度約束,決定可用的功能組合)
 
-**無高度約束**（auto）
-- 內容決定高度，table 框只包住內容
-- 適合少量資料、預覽、嵌入式表格
-- 犧牲：無虛擬捲動（全部渲染）、header 隨頁面捲走、水平捲軸在 table 最底部
-- 這些不是 bug，是模式的取捨
+- **有高度約束**(固定 `height="400px"` 等具體 px/rem,或 `height="100%"` 由父 flex 提供約束,Linear 做法——都走相同 cap 行為,無 dead surface):資料少→outer 內容高度;資料多→撐到上限後內部 scroll(虛擬捲動啟用,header 固定)
+- **無高度約束**(auto):內容決定高度,table 框只包住內容;適合少量資料、預覽、嵌入式表格。犧牲:無虛擬捲動(全部渲染)、header 隨頁面捲走、水平捲軸在 table 最底部——這些不是 bug,是模式的取捨
 
 ### 三、三區域架構（AG Grid 模式）
 
 Table 分三層:
-- **Header**(固定頂部,不在 scroll 容器內):含 left / center / right 三區,center 區與 body center 的水平捲動 JS 同步 scrollLeft
-- **Body viewport**(垂直可捲,橫向由 center 區負責):含 left / center / right 三區,只有 center 可水平捲動,left / right 不隨水平捲動
-- **Left / Right 區**:寬度由凍結欄加總,不吃水平捲動;**Center 區**:flex-1,水平 overflow 自行處理
+- **Header**(固定頂部,結構性地在 scroll 容器外、body 上方——不用 CSS sticky,永遠固定在頂部):含 left / center / right 三區,center 區與 body center 的水平捲動 JS 同步 scrollLeft(center-header 跟隨 center-body 捲動位置,同步機制見「捲軸」段 + `data-table.tsx`)。Header bg 用 `--muted`(code `HEADER_BG = 'bg-muted'`,比 surface 深一階,同 anatomy ColorMatrix)
+- **Body viewport**:含 left / center / right 三區;center-body 是唯一的水平 scroll container、也是垂直 scroll container(`overflow-y-auto`),left / right body 不自行捲動(`overflow-hidden`,`scrollTop` 由 center 的 `onScroll` 同步兩側;AR44:V scroll 移進 region 自身,讓水平捲軸落在可視視窗底部,不必捲到內容底才看到)
+- **Left / Right 區**:寬度由凍結欄加總,不吃水平捲動;frozen 邊界線用 `.dtPanelBoundaryRight/Left` 的 `box-shadow: inset` 1px `var(--divider)`(paint-only 不佔 box model;2026-05-12 自 `border-divider` 改制 — Windows 常駐捲軸會蓋掉 outer-edge border),header + body panel 各套,視覺整欄高度;**Center 區**:flex-1,水平 overflow 自行處理
 
 完整 class / overflow 規則見 `data-table.tsx`。
 
-**Header 在 scroll 容器外面。** 不用 CSS sticky——header 結構性地在 body 上方，永遠固定在頂部。Header bg 用 `--muted`（code `HEADER_BG = 'bg-muted'`,比 surface 深一階,同 anatomy ColorMatrix）。
-
-**三個 region 共享垂直捲動。** body-viewport 是唯一的垂直 scroll container，三個 body region 是它的 flex children。垂直捲動天然同步，不需 JS。
-
-**只有 center 水平捲動。** center-body 是唯一的水平 scroll container,center-header 跟隨其捲動位置同步（同步機制見「捲軸」段 + `data-table.tsx`）。
-
-**Left / right 不水平捲動。** Frozen 邊界用 `border-divider`（全高度）。
-
 **固定行高確保跨 region 對齊。** 所有 row 用 `h-table-row-{size}`，三個 region 的 row 精確同高。
 
 **Header/body region 寬度同步。** Header region 寬度由內容決定（columns + actions），body region 量測 header 寬度同步（機制見 `data-table.tsx`）。
@@ -121,15 +96,8 @@ Table 分三層:
 
 Table 層級的模式切換，不是 column 層級。跟 AG Grid / Airtable 的做法一致。
 
-**固定行高（預設）**——適合大多數場景
-- 所有 row 同高，內容垂直置中
-- 文字、tag、badge、avatar 等不同高度的元件都自然居中，不需要處理對齊
-- 文字一律截斷，不換行（column 的 `wrap: true` 被忽略）
-
-**自動行高**——適合有描述、備註等需要完整顯示的欄位
-- Row 高度由最高的 cell 決定，內容頂部對齊
-- 垂直 padding 由目標行高推導，單行時製造置中效果，多行時保持頂部對齊
-- `wrap: true` 的欄位可換行撐高 row
+- **固定行高（預設，適合大多數場景）**：所有 row 同高、內容垂直置中——文字、tag、badge、avatar 等不同高度的元件都自然居中，不需處理對齊；文字一律截斷不換行（column 的 `wrap: true` 被忽略）
+- **自動行高（適合描述、備註等需完整顯示的欄位）**：row 高度由最高的 cell 決定、內容頂部對齊；垂直 padding 由目標行高推導（單行時製造置中效果，多行時保持頂部對齊）；`wrap: true` 的欄位可換行撐高 row
 
 ### 五、Header vs Body 的視覺區隔
 
@@ -140,31 +108,19 @@ Table 層級的模式切換，不是 column 層級。跟 AG Grid / Airtable 的
 | Header 分隔線 | 僅 header 區域（上下留 padding） | 一般非 frozen 欄位之間 |
 | Frozen 邊界線 | **整欄高度**（table 頂部到底部） | frozen column 與 scrollable area 的交界 |
 
-一般 column 只在 header 有短線——body 的欄位邊界由 header 引導，不需額外視覺噪音。但 frozen column 的邊界是結構性的分隔（固定區域 vs 捲動區域），需要全高度的線來明確標示。
-
-Row actions 欄本質上是 frozen right column，左邊界也使用 full-height 分隔線。
+一般 column 只在 header 有短線——body 的欄位邊界由 header 引導，不需額外視覺噪音。但 frozen column 的邊界是結構性的分隔（固定區域 vs 捲動區域），需要全高度的線來明確標示。Row actions 欄本質上是 frozen right column，左邊界也使用 full-height 分隔線。
 
 **Header 文字弱化。** Header 是結構標籤，不是資訊本體。字體與 body 相同但使用次要文字色，搭配 muted 背景拉出層級，讓視覺重心留在 body 的資料上。
 
 ### 六、外框規則
 
-**邊框標記「這裡有使用者看不到的內容」。** 沒有邊框時，使用者無法判斷內容是否有溢出。
-
-加框的條件（滿足任一即加）：
-- **垂直捲動**（有高度約束，內容超出容器）
-- **水平溢出**（欄位總寬超過容器）
-- **有 frozen column**（固定欄與捲動區域的陰影分界需要外框歸屬）
-- **全表 inline edit**（可編輯容器需要邊界提示）
-
-不加框時，最後一行保留底線自然收尾。加框時最後一行底線去掉，避免與外框 double border。
+**邊框標記「這裡有使用者看不到的內容」。** 沒有邊框時，使用者無法判斷內容是否有溢出。加框的條件（滿足任一即加）：**垂直捲動**（有高度約束，內容超出容器）／**水平溢出**（欄位總寬超過容器）／**有 frozen column**（固定欄與捲動區域的分界線需要外框歸屬）／**全表 inline edit**（可編輯容器需要邊界提示）。
 
-**Prop**：`bordered`（boolean，預設 `true`）。多數場景（有高度約束的虛擬捲動 / frozen column / inline edit 表）都應保持預設；只在**資料量極少、無溢出、嵌在 Card / Section 內已有外框**的展示型場景傳 `bordered={false}` 讓最外層視覺收尾。
+不加框時，最後一行保留底線自然收尾。加框時最後一行底線去掉，避免與外框 double border。**Prop**：`bordered`（boolean，預設 `true`）。多數場景（有高度約束的虛擬捲動 / frozen column / inline edit 表）都應保持預設；只在**資料量極少、無溢出、嵌在 Card / Section 內已有外框**的展示型場景傳 `bordered={false}` 讓最外層視覺收尾。
 
 ### 六之二、Column 寬度 API + 不變條件(2026-05-06 v14.3)
 
-**命名**:`meta.width` / `meta.minWidth` / `meta.maxWidth`(px)。**不用 TanStack `size`** — DS 內 `size` 既定為 `'sm'|'md'|'lg'` density(49+ 處),避 namespace 衝突。內部 pre-process copy 到 TanStack root,resize feature 正常。No-resize default:`width` = reserve(cell ≥ width,flex 可 grow,不可 shrink)。`enableColumnResize=true`:`width` = 初始,`minWidth` = 拖拉下限(default 80)。
-
-**不變條件(invariants,L2 test + hook 守)**:(1) cell width = column width(跟 padding/state/mode 無關)(2) display↔edit cell width 0 delta (3) display↔edit cell height 0 delta(textarea `field-sizing:content`)(4) Field 填滿 cell 高度(1px 容差於 cell.border-r)(5) No-resize column ≥ meta.width。對應 `scripts/data-table-invariants.mjs`。改 `columnSizeStyle` / 切 layout 必跑 invariant test 才 commit。
+**命名**:`meta.width` / `meta.minWidth` / `meta.maxWidth`(px)。**不用 TanStack `size`** — DS 內 `size` 既定為 `'sm'|'md'|'lg'` density(49+ 處),避 namespace 衝突。內部 pre-process copy 到 TanStack root,resize feature 正常。No-resize default:`width` = reserve(cell ≥ width,flex 可 grow,不可 shrink)。`enableColumnResize=true`:`width` = 初始,`minWidth` = 拖拉下限(default 80)。**不變條件(invariants,L2 test + hook 守)**:(1) cell width = column width(跟 padding/state/mode 無關)(2) display↔edit cell width 0 delta (3) display↔edit cell height 0 delta(textarea `field-sizing:content`)(4) Field 填滿 cell 高度(1px 容差於 cell.border-r)(5) No-resize column ≥ meta.width。對應 `scripts/data-table-invariants.mjs`。改 `columnSizeStyle` / 切 layout 必跑 invariant test 才 commit。
 
 ### 六之三、Runtime perf budget canonical(2026-05-14 codex+Layer A)
 
@@ -179,7 +135,7 @@ Row actions 欄本質上是 frozen right column，左邊界也使用 full-height
 
 **2026-06-12 重建後實測**(static build,3 runs/case):1x CPU — A 16.56/16.8/0、B 24.0/33.4/0、C 16.67/16.8/0 全過 gate;script 預設 4x throttle 在有背景負載機器上全 case 一致 ~2.3x 超標(含未動過的對照組 A)→ 本表門檻實證對應 1x/閒置條件,4x 門檻是否重校 = user 決策(本表數字不動)。
 
-**Anti-pattern**:`RoadmapAllInOne`(全 features stack)≈117ms 不達 B,因 SortableRowProvider/column reorder/resize/selection/overlay 同時開。Consumer:13+ cols rich-cell → 拆 detail drawer / column visibility 預設 hide,不該期 60fps + 全 feature stack。Cite + Phase 1/2 history → `cell-registry.tsx:480-499` JSDoc + commits log。
+**Anti-pattern**:`RoadmapAllInOne`(全 features stack)≈117ms 不達 B,因 SortableRowProvider/column reorder/resize/selection/overlay 同時開。Consumer:13+ cols rich-cell → 拆 detail drawer / column visibility 預設 hide,不該期 60fps + 全 feature stack。Cite + Phase 1/2 history → `cell-registry.tsx` perf-fix JSDoc(`buildCellWithSurface` 上方)+ commits log。
 
 ### 七、Column Type
 
@@ -192,24 +148,13 @@ Row actions 欄本質上是 frozen right column，左邊界也使用 full-height
 
 ### 九、Row Actions
 
-每列最右側可配置操作(編輯、刪除、複製等)。位於 right-pinned region(全高 `border-divider` 分隔),不參與水平捲動,**常駐顯示**(對齊 dense data ops 派)。
-
-**Canonical**:Row actions 一律 `Button iconOnly variant="text" size="xs"`(固定 24px),不隨 row tier 放大,**不套 `dismiss` prop**(Trash/Delete = `onRemove` 語意,不是 dismiss)。
+每列最右側可配置操作(編輯、刪除、複製等)。位於 right-pinned region(全高 1px `var(--divider)` 分隔線,機制見「三區域架構」frozen 邊界),不參與水平捲動,**常駐顯示**(對齊 dense data ops 派)。
 
-**Why 固定 24**:row actions 是「dense utility affordance」(輔助 ≠ 資料本體),固定 24 讓資料 cell 為視覺重心;放大會違反「data 本體 / action 輔助」階層。對照 `patterns/element-anatomy/inline-action.spec.md` Real case 表「DataTable row dedicated action column」row。
+**Canonical**:Row actions 一律 `Button iconOnly variant="text" size="xs"`(固定 24px),不隨 row tier 放大,**不套 `dismiss` prop**(Trash/Delete = `onRemove` 語意,不是 dismiss)。**Why 固定 24**:row actions 是「dense utility affordance」(輔助 ≠ 資料本體),固定 24 讓資料 cell 為視覺重心;放大會違反「data 本體 / action 輔助」階層。對照 `patterns/element-anatomy/inline-action.spec.md` Real case 表「DataTable row dedicated action column」row。
 
 **世界級對照**:Material DataGrid `GridActionsCellItem`(IconButton small)/ Polaris IndexTable hover 20-24px / Atlassian Dynamic Table small iconOnly / Apple HIG Finder list row ≤24px — 全派固定不放大。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-**收納邏輯：**
-
-| 數量 | 顯示方式 |
-|------|----------|
-| 1-2 | icon buttons 並排(全 size="xs")|
-| 3+ | 前 1-2 個 inline + MoreVertical dropdown(全 size="xs") |
-
-MoreVertical dropdown 包含所有操作，確保鍵盤可存取全部。
-
-**Header/body 寬度同步：** Header 渲染 invisible buttons 佔位(同 size="xs"),確保 header 和 body 的 right region 同寬。
+**收納邏輯**:1-2 個 → icon buttons 並排(全 size="xs");3+ → 前 1-2 個 inline + MoreVertical dropdown(全 size="xs";dropdown 包含所有操作,確保鍵盤可存取全部)。**Header/body 寬度同步**:header 渲染 invisible buttons 佔位(同 size="xs"),確保 header 和 body 的 right region 同寬。
 
 ### 九之二、Cell action primitive 分類(2026-04-29 codified)
 
@@ -227,13 +172,11 @@ SSOT → `patterns/element-anatomy/inline-action.spec.md`「Real case 表」+ Pr
 
 ### 十、與 Toolbar 的關係
 
-DataTable 不內建 toolbar。Toolbar 是外部用 action-bar pattern 組合的，保持職責分離。
-
-篩選、排序、分組走統一入口（toolbar 按鈕），不做在表頭的 per-column filter。這些按鈕的 variant 規則見 `action-bar.spec.md`。
+DataTable 不內建 toolbar。Toolbar 是外部用 action-bar pattern 組合的，保持職責分離。篩選、排序、分組走統一入口（toolbar 按鈕），不做在表頭的 per-column filter。這些按鈕的 variant 規則見 `action-bar.spec.md`。
 
 ### 十一之一、Cell 垂直對齊 + icon canonical
 
-Cell 已 `flex items-center`,consumer render 直接 inline-flex + gap-2。Icon size:sm/md→16 / lg→20(對齊 Field family,禁 14/18/24 自由挑)。`renderCellContent` 對 `React.isValidElement(content)` true / `isKnownCompound`(select/multiSelect/person/url)bypass TruncateCell;primitive 才走 truncate + hover tooltip。❌ consumer wrapper 加 `leading-none` / `h-full` / `align-middle` 治標 — 根因常在 TruncateCell 包覆。
+Cell 已 `flex items-center`,consumer render 直接 inline-flex + gap-2。Icon size:sm/md→16 / lg→20(對齊 Field family,禁 14/18/24 自由挑)。`renderCellContent` 對 `React.isValidElement(content)` true / `isKnownCompound`(select/multiSelect/person/multiPerson/url/date/time)bypass TruncateCell;primitive 才走 truncate + hover tooltip。❌ consumer wrapper 加 `leading-none` / `h-full` / `align-middle` 治標 — 根因常在 TruncateCell 包覆。
 
 ### 十一、Cell 單行截斷原則
 
@@ -249,9 +192,7 @@ DataTable 只管「column + data」;Loading / Error / Disabled-整表由 consume
 
 ## 捲軸(pinned header / column + scroll canonical)
 
-3-panel(left-pinned / center-scroll / right-pinned),center body 用 **native `overflow-x-auto`**(非 ScrollArea),header 透過 JS `onScroll` 同步 scrollLeft。對齊 Linear / Notion / Airbnb / Ant ProTable / TanStack 主流。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-
-**不用 `<ScrollArea>` 的理由**:Radix viewport nested div 會 break scrollLeft 同步;pinned column 需「左右獨立 scroll + 中央共享 scroll state」,單一 viewport 不適配。
+3-panel(left-pinned / center-scroll / right-pinned),center body 用 **native `overflow-x-auto`**(非 ScrollArea),header 透過 JS `onScroll` 同步 scrollLeft。對齊 Linear / Notion / Airbnb / Ant ProTable / TanStack 主流。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL --> **不用 `<ScrollArea>` 的理由**:Radix viewport nested div 會 break scrollLeft 同步;pinned column 需「左右獨立 scroll + 中央共享 scroll state」,單一 viewport 不適配。
 
 **Tech debt**:macOS auto-hide vs Windows/Linux 常駐 scrollbar,cross-OS 視覺寬度差異 — consumer 可 override `::-webkit-scrollbar` 樣式;ScrollArea 重構列 post-v1。
 
@@ -259,9 +200,7 @@ DataTable 只管「column + data」;Loading / Error / Disabled-整表由 consume
 
 ## L2:選取(Selection)
 
-DataTable 的 row selection layer。提供 controlled/uncontrolled state + 視覺 + 鍵盤,搭配獨立 `BulkActionBar` primitive 完成批次 workflow。
-
-**世界級對照**:Material DataGrid `rowSelectionModel` / Polaris IndexTable `selectedResources` / Linear / Notion 全 controlled-first + uncontrolled fallback。AG Grid 的 imperative `gridRef.api` 不採(違背 React idiom + 既有 Field/Switch/Checkbox controllable 慣例)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+DataTable 的 row selection layer。提供 controlled/uncontrolled state + 視覺 + 鍵盤,搭配獨立 `BulkActionBar` primitive 完成批次 workflow。**世界級對照**:Material DataGrid `rowSelectionModel` / Polaris IndexTable `selectedResources` / Linear / Notion 全 controlled-first + uncontrolled fallback。AG Grid 的 imperative `gridRef.api` 不採(違背 React idiom + 既有 Field/Switch/Checkbox controllable 慣例)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ### 一、State 模式(discriminated union,2026-06-22 支援反向選取 inverted)
 
@@ -275,7 +214,7 @@ selection?: string[] | DataTableSelection         // controlled;傳 string[] = i
 defaultSelection?: string[] | DataTableSelection  // uncontrolled
 onSelectionChange?: (next: DataTableSelection) => void  // 一律 emit union
 totalCount?: number                   // 全集筆數 M(server-side / filter 後);all 模式計數用
-selectable?: boolean | 'single' | 'multi'  // default 'multi';single 永遠 include
+selectable?: boolean | 'single' | 'multi'  // default false(不啟用);true 等同 'multi';single 永遠 include
 isRowSelectable?: (row: TData) => boolean
 preserveSelectionOnFilter?: boolean   // default false
 ```
@@ -285,7 +224,7 @@ preserveSelectionOnFilter?: boolean   // default false
 ### 二、Checkbox column
 
 - **位置**:最左,自動 left-pin(不論 consumer pin 哪些 cols)
-- **寬度**:對稱 row-actions 區寬
+- **寬度**:固定 40px(system col;不可 resize、不可隱藏)
 - **顯示時機**:**always visible**(對齊 Linear 2024 / Polaris / Material consensus,不允 hover-show) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **Header tri-state**:none / indeterminate / all,使用既有 Checkbox `indeterminate` prop
 
@@ -322,12 +261,12 @@ preserveSelectionOnFilter?: boolean   // default false
 
 ### 七、BulkActionBar 整合(inline composition canonical)
 
-`BulkActionBar` 是獨立 primitive(`../BulkActionBar/`),不內建。Consumer flex-column 容器 inline composition,**toolbar 永遠保留**(filter / sort / search selection 期間仍可用,additive 派 — 對齊 Linear / Notion / Apple Mail / iOS Files)。Hint banner 用 `<Alert variant="info" placement="fixed">` + ReactNode title。4 layout use case 詳 `../BulkActionBar/bulk-action-bar.spec.md`。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+`BulkActionBar` 是獨立 primitive(`../BulkActionBar/`),不內建。Consumer flex-column 容器 inline composition,**toolbar 永遠保留**(filter / sort / search selection 期間仍可用,additive 派 — 對齊 Linear / Notion / Apple Mail / iOS Files)。Hint banner 用 `<Alert variant="neutral" placement="fixed">` + ReactNode title(資訊性 hint 非 info hue,canonical 見 `data-table.stories.tsx` WithBulkActions)。4 layout use case 詳 `../BulkActionBar/bulk-action-bar.spec.md`。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ### 八、a11y 預設
 
 - 每個 row checkbox 必有 `aria-label`:consumer 提供 `getRowAriaLabel?: (row) => string`,fallback `"Select row"`
-- header checkbox `aria-label="Select all visible rows"`
+- header checkbox `aria-label="全選可見列"`
 - 鍵盤:`Space` toggle / `Shift+Space` 擴 range / `Cmd/Ctrl+A` 選全可見 / `Esc` clear
 - Selection 變更可選 `aria-live="polite"` 通知(consumer-implemented)
 - **Multi mode 用 Checkbox / Single mode 用 Radio**(對齊 Material DataGrid / Polaris IndexTable 共識,same-row consistency 全 sm)。Single mode 內部 wrap `RadioGroupPrimitive.Root` 提供 context,header checkbox 抑制(single 無「全選」概念)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
@@ -344,9 +283,7 @@ preserveSelectionOnFilter?: boolean   // default false
 
 ## L4:Advanced Filter(進階篩選 panel)
 
-DataTable toolbar 的「篩選」按鈕展開 `<DataTableFilterPanel>` — flat 或 1-level nested boolean expression builder。實作 sub-file `data-table-filter-panel.tsx`(同 SortManager 對齊 sub-file pattern,**不另開 5-file**:spec / stories 都消費本檔)。
-
-**M8 對標**:ClickUp 為主 + Notion / Airtable / Coda / Linear。Image ref:user 提供 ClickUp-style 截圖(2026-05-02)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+DataTable toolbar 的「篩選」按鈕展開 `<DataTableFilterPanel>` — flat 或 1-level nested boolean expression builder。實作 sub-file `data-table-filter-panel.tsx`(同 SortManager 對齊 sub-file pattern,**不另開 5-file**:spec / stories 都消費本檔)。**M8 對標**:ClickUp 為主 + Notion / Airtable / Coda / Linear。Image ref:user 提供 ClickUp-style 截圖(2026-05-02)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ### 一、Mode
 
@@ -364,7 +301,7 @@ type FilterTreeNested = { mode: 'nested'; conjunction: 'and'|'or'; children: Fil
 
 ### 二、求值策略
 
-採 TanStack `globalFilter` + 自訂 `globalFilterFn(row, _, tree) => evaluateTree(tree, row.original)`,**棄 `columnFilters`**(N 條同 column 不能 OR)。`evaluateTree` SSOT 在 `filter-tree.ts`。**ms-precision when `meta.includeTime=true`**:datetime 比對檢查 column meta,`true` 走 ms 比對(避開 Airtable day-precision 漏邊界地雷)。
+採 TanStack `globalFilter` + 自訂 `globalFilterFn(row, _, tree) => evaluateTree(tree, row.original)`,**棄 `columnFilters`**(N 條同 column 不能 OR)。`evaluateTree` SSOT 在 `filter-tree.ts`。**比對精度(2026-07-04 Q6 實作)**:panel 建 condition 時把 `meta.includeTime` 固化為 `condition.datePrecision`('ms' / 'day';`evaluateTree` 簽名不變)— date ops 預設 day 級(本地 `startOfDay` 截斷,AG Grid / MUI X 慣例;`is` 同步走日期比對非字串),`includeTime=true` 才 ms 全精度(避開 Airtable day-precision 漏邊界地雷)。
 
 ### 三、Operator × ValueShape SSOT
 
@@ -382,14 +319,14 @@ ValueShape ↔ DS picker 對照(canonical 2026-05-02):
 | `datetime_single` | `<DatePicker showTime>` | `meta.includeTime=true` 時 promote |
 | `datetime_range` | `<DatePickerRange showTime>` | 同上 |
 | `select_multi` | `<Combobox>` | |
-| `person_multi` | `<PeoplePicker multi>` 預留 | v1 fallback Input |
+| `person_multi` | `<PeoplePicker>` 多選 | 2026-05-07 升級為真 picker,吃 `column.meta.people` |
 
 ### 四、UI canonical
 
 - 第 1 row conjunction 是靜態 `Where` label(`px-[var(--field-px)]` 對齊下方 Field value 起點 = 12px)
-- field 未選 → operator + value picker disabled;同 group 共用 conjunction(toggle 任一 → flip 整 group)
-- **空狀態**:無 condition → 只顯 inline `+ 加篩選` CTA(對齊 Notion / Airtable / Linear,**禁止** auto-create 空 row) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **CTA 位置**:緊貼最後一條 row(text variant 輕量,**廢 SurfaceFooter**),條件與「加入」屬同一語境
+- field 未選 → operator + value picker disabled;同 group 共用 conjunction(第 2 條 row 是唯一可改的 And/Or Select,改動連動整 group;第 3 條起唯讀顯示當前 conjunction — A6 canonical)
+- **空狀態(兩態,G fix 2026-05-04 v2)**:initial mount 且 value 空 → auto-add 1 條空 condition row(field 未選 → operator / value 自動 disabled;讓 user 直接看到 row shape,不必先點 CTA;useRef gate 只 mount 一次);user 手動刪光 → 只顯 inline `+ 加篩選` CTA、不 re-add(尊重清空意圖,對齊 Notion / Airtable / Linear) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **CTA 位置**:緊貼最後一條 row(**廢 SurfaceFooter**),條件與「加入」屬同一語境;root-level「加篩選 / 加入篩選器」用 `tertiary`(輕量但有邊界,符合 root-CTA 重量),group 內「加入巢狀篩選」才用 `text`(更輕,inline 於 group 內)
 - **Trash / 刪除**:row 是 form-control row → text Button(non Inline Action,違 item-anatomy canonical)
 - **And/Or Select** `minRows={2}`(2 選項顯式縮 menu 高度);**Where padding** `px-[var(--field-px)]` align Field
 - Header refresh icon:`value !== defaultValue` 顯;ButtonDivider 串接 close X(對齊欄位顯示 chrome canonical)
@@ -400,7 +337,7 @@ ValueShape ↔ DS picker 對照(canonical 2026-05-02):
 
 | 條件 | 是否出現 |
 |------|---------|
-| Display column(無 `accessorKey`)| ❌ TanStack 內建限制 |
+| Display column(無 `accessorKey`)| ❌ 慣例排除 — 判定實際只看 `meta.type`(display column 不設 type 即不出現;非 TanStack 機械限制,設了 type 仍會列入)|
 | Accessor + 有 `meta.type` | ✅ 預設 |
 | Accessor + `meta.filterable: false` | ❌ opt-out |
 | Accessor + 無 `meta.type` | ❌ 無 type 無法決定 op set |
@@ -418,13 +355,11 @@ ValueShape ↔ DS picker 對照(canonical 2026-05-02):
 
 ---
 
-## L4 Inline Edit / Nested rows / Row drag(2026-05-04)
-
-對齊 Notion / Airtable type-aware editor + Jira drag idiom @benchmark-unverified。
+## L4 Inline Edit / Nested rows / Row drag(2026-05-04;對齊 Notion / Airtable type-aware editor + Jira drag idiom @benchmark-unverified)
 
 ### Inline Edit — per-column opt-in
 
-`columnDef.meta.editable: boolean | (row) => boolean`(`true` / fn-true 才開)。Commit:blur or Enter → `onCellCommit(rowId, colId, value)`;Cancel:Esc。
+`columnDef.meta.editable: boolean | (row) => boolean`(`true` / fn-true 才開)。Commit:blur or Enter → `onCellCommit(rowId, colId, value)`;Cancel:Esc。例外:autoRowHeight string cell 的 edit 是 `Textarea` — Enter 換行、`Cmd/Ctrl+Enter` commit(blur 同 commit)。
 
 | ColumnType | Trigger | Edit mode |
 |--|--|--|
@@ -458,13 +393,36 @@ Row drag + column reorder + TreeView 共用 `lib/drag-visual.ts`:source `opacity
 
 - **Handle**:Button tertiary iconOnly xs(GripVertical)24px chip,所有 state(idle / hover / aria-disabled)統一 `bg-surface-raised`(border / shadow 已 retire,2026-05-12 per user「我有叫你加 elevation 嗎」),fixed-position 浮層貼 row 左緣、不佔 column 空間(位置 JS 計算,實作見 `data-table.tsx`);**hover-reveal** 由 JS 控 visibility / opacity(row 或 handle hover 顯示;drag 中 source 強制顯示、其他列隱藏)。對齊 Jira backlog(@benchmark-unverified,M22)。Tertiary chip 非 ItemInlineAction 因透明背景撞 table border。
 - **Sort × Drag 互斥**:sort.length>0 → handle disabled+Tooltip。**Top-level only**(`row.depth>0` 不顯 handle)。**Position**:active vs over 視覺位置 → `'after'`/`'before'` 對齊 `arrayMove`。**Consumer-managed mutation**:`onRowReorder(sourceId, targetId, position)`,DS 不持 row order(Notion/Airtable/Linear)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **Virtualization 整合**(v3 2026-05-05):enableRowDrag 自動把 overscan 拉到 `Math.max(overscan, 5)` + drag 期 freeze `measureElement` + `modifiers={[snapToCursorModifier]}`(ghost top-left 對齊 cursor,不鎖軸)。**3-panel mirror sync**:各 region 對同 row id 各呼叫 `useDraggable` + `useDroppable`,mirror 自然取得相同 transform;handle 只 render primary region(left 優先 → center)避雙觸發。**Cross-parent drop 禁止**(已知 limit):nested 只同 top-level 重排,collisionDetection 過濾,顯 invalid signal。
+- **Virtualization 整合**(v3 2026-05-05):enableRowDrag 自動把 overscan 拉到 `Math.max(overscan, 5)` + drag 期 freeze `measureElement` + `modifiers={[snapToCursorModifier]}`(ghost top-left 對齊 cursor,不鎖軸)。**3-panel mirror sync**:primary 永遠 = center region(v15.4 撤銷「left 優先」— multi-instance same-id 是 dnd-kit anti-pattern,且 pinned column 是「鎖定欄」語意非 drag 起點),只有 center 掛 `useDraggable`;mirror region(left / right pinned)只掛 `useDroppable`,drag 期以 `useDndContext` 同步 source 半透視覺(Path B source 留原位,無 row transform);handle 只 render primary(center)避雙觸發。**Cross-parent drop 禁止**(已知 limit):nested 只同 top-level 重排,collisionDetection 過濾,顯 invalid signal。
+
+---
+
+## L5:分頁(Pagination,2026-07-06)
+
+**共用模式(user 拍板)**:`Pagination` 獨立公開元件是頁碼視覺 SSOT(`../Pagination/pagination.spec.md`,細節不在此重述);DataTable 加 `pagination` prop 內建消費它——內部接 TanStack `getPaginationRowModel()`,表格下方 render 分頁列。對齊 Ant Table(消費 Pagination)/ Atlassian DynamicTable(`rowsPerPage`)/ MUI DataGrid 內建派;shadcn data-table 教學同款「分頁 render 在 DataTable 元件 JSX 內」。
+
+**API**:`pagination?: boolean | DataTablePaginationOptions`——`{ pageSize?(**uncontrolled 初始值**,預設 20;之後變更由使用者操作選單驅動、經 onPageSizeChange 回報,動態改此欄位不生效——controlled 需求列 v2。注意與 Pagination 元件的 pageSize prop 語意不同:那是 controlled)、pageSizeOptions?(傳了才渲染「每頁 N 筆」Select sm)、showTotal?(傳 true 才渲染 range 資訊,= Ant showTotal opt-in 邏輯)、page? / defaultPage? / onPageChange?(1-based dual-mode)、onPageSizeChange? }`。v1 = **client-side only**(全量 data 進來由 TanStack 切頁);server-side(`manualPagination` + 外部 total)列 v2。
+
+**分頁列(bar)規則**:
+- **bar 本體 SSOT 在 `<Pagination>` 完整形態**(2026-07-06 user 拍板「Pagination 元件提供完整功能、Table 按一致定義套用」):showTotal range 資訊、「N 筆/頁」選單、「資訊左、操作右」layout 全在 `../Pagination/pagination.spec.md`「完整形態」段——DataTable **只轉發 config + own TanStack state**(controlled 消費),不自拼分頁列
+- **間距**:表格 → 分頁列 = `--layout-space-tight`(layoutSpace spec 規則 3「跨範疇 functional 交互」;Ant Table margin 16px / shadcn py-4 同量級)
+- **對齊**:純頁碼形態**靠右**(shadcn `justify-end` / Ant Table 預設 `bottomEnd` / MUI TablePagination / Carbon 控制群 4 家實證);完整形態由 Pagination 自帶 w-full justify-between
+- **`total` 數源** = `getPrePaginationRowModel().rows.length`(filter 後全集)——**不是** selection all-mode 的 `totalCount` prop(那是 server-side 全集數,語意不同)
+- filter / data 縮小時自動 clamp 當前頁(對齊 MUI X);`isEmpty` 時分頁列整條不渲染(Empty 已渲染)
+
+**與虛擬滾動互斥**:啟用分頁 → `useVirtual` 強制關閉——TanStack 官方定位兩者為互斥替代策略(分頁 = 每頁固定筆數主動換頁;虛擬滾動 = 連續滾動只渲可視列)。分頁時無虛擬化保護,建議 `pageSize ≤ 100`。
+
+**height 預設連動**:未顯式傳 `height` 時,啟用分頁預設 **`'auto'` 自然高度**(hug 當前頁)——頁碼是分頁的唯一導覽通道,再疊 body 內捲動 = 雙重導覽(一頁 20 筆只露 10 筆);對齊 Ant Table 無預設高度罩、`scroll.y` 顯式選配慣例。未分頁維持既有 `'400px'` 預設;**顯式傳 height 一律尊重**(分頁 + 頁內捲動可並用)。
+
+**Selection 交互**:header checkbox「全選」= 當頁可見列(page-scoped,rows 即當頁);跨頁已選 ids 翻頁不清除;BulkActionBar 2-step「已選本頁 N → 選全部 M」語意與分頁天然契合(見 L2 段)。`aria-rowcount` = 全集筆數 + 1(非當頁,ARIA 規範)。
+
+**禁止**:❌ 分頁 + 期待虛擬滾動同時生效;❌ 繞過 prop 在表格下方自行手排 standalone `<Pagination>`(間距/對齊/互斥全部走本段 canonical)。
 
 ---
 
 ## Overlay + cell error SSOT(Phase 9)
 
-**Overlay**:viewport `position:fixed inset:0` layer。`getCellRect()` 從 `getBoundingClientRect()` 取 float coords no rounding。Paint:hover/selected/range outer ring `outline outline-offset:-1px` in-place;active editor host portal opaque `<div>` z 3(cell 保持 display)。**Viewport clip**(Issue 6):body panel 加 `data-datatable-panel="left|center|right"`;`getCellGeometry()` return cell+panel rect;`<ClipMask>` panel rect `overflow:hidden`,內部 `toRelRect()` 轉 mask-relative。Range outer ring 按 panel 分組(避 bbox 跨 pin boundary)。Active editor host **不 clip**。對齊 AG Grid `cellsForRangeSet` / Glide / Notion sticky-cell mask。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Overlay**:viewport `position:fixed inset:0` layer。`getCellRect()` 從 `getBoundingClientRect()` 取 float coords no rounding。Paint:hover/selected ring `outline outline-offset:-1px` in-place(range outer ring 已 2026-05-10 retire — range 視覺只剩 cell-bg `--primary-subtle` `[data-range-cell]`,bg 已足以標示範圍、外框冗餘);active editor host portal opaque `<div>` z 3(cell 保持 display)。**Viewport clip**(Issue 6):body panel 加 `data-datatable-panel="left|center|right"`;`getCellGeometry()` return cell+panel rect;`<ClipMask>` panel rect `overflow:hidden`,內部 `toRelRect()` 轉 mask-relative(hover/selected ring 按 panel clip,不畫出 pin boundary)。Active editor host **不 clip**。對齊 AG Grid `cellsForRangeSet` / Glide / Notion sticky-cell mask。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 **Cell errors**(Issue 9):`cellErrors?: Record<string, string|string[]>` prop key `${rowId}:${colId}`。Cell display 渲 error 14px `text-error` 下方 gap-1;array→`<ul><li>`;single→`<span>`。`aria-describedby` + `aria-invalid` + `<span role="alert">`。`overflow:visible` 當有 error(搭 `autoRowHeight`)。**Per-row state SSOT** cell-render wrapper(`items-X` 等)必 consume `effectiveAutoRowForCell`,禁 global `autoRowHeight`(audit `audit-data-table-row-mode-ssot.mjs` 強制)。**Edit-clears-own-cell** 自動清視覺,consumer onCellCommit validate 後回填。**a11y caveat**:≥ 5 同時 `role="alert"` 第一次 paint AT 噪音 → consumer 可考 `role="status"` fallback。對齊 AG Grid `cellClassRules='ag-cell-error'` + Material X errorMessage + Airtable validation。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
@@ -486,7 +444,7 @@ Row drag + column reorder + TreeView 共用 `lib/drag-visual.ts`:source `opacity
 
 ## Anatomy 結構例外
 
-DataTable 是 composite multi-section 元件,**不套 canonical 5**(Inspector / SizeMatrix / StateBehavior)而採「按區塊 + 按 feature」拆:`Overview` / `ColumnTypes` / `RowHeightMatrix`(對應 row-height tier 而非 component size)/ `AlignmentRule` / `Features` / `ColorMatrix`(row 多 state 集中)/ `EmptyState`(消費 Empty primitive)。理由:單一 Inspector 無法呈現「資料 schema → column type 對應」這類跨 prop 決策。
+DataTable 是 composite multi-section 元件,**不套 SizeMatrix / StateBehavior**(由 `RowHeightMatrix` / `ColorMatrix` 對應)而採「按區塊 + 按 feature」拆:`Overview` / `Inspector`(props 即時檢閱)/ `ColumnTypes` / `RowHeightMatrix`(對應 row-height tier 而非 component size)/ `AlignmentRule` / `Features` / `ColorMatrix`(row 多 state 集中)/ `EmptyState`(消費 Empty primitive)/ `BorderedProp` / `Accessibility`。理由:單一 Inspector 無法呈現「資料 schema → column type 對應」這類跨 prop 決策,Inspector 之外仍按 feature 拆。
 
 ---
 
@@ -498,12 +456,12 @@ DataTable 是 composite multi-section 元件,**不套 canonical 5**(Inspector /
 - `../TreeView/tree-view.spec.md` — 階層結構的對應元件
 - `../../tokens/uiSize/uiSize.spec.md` — `--table-row-*` / `--field-height-*` token
 - `../../tokens/color/color.spec.md` — 語義色彩
-- `../../tokens/elevation/elevation.spec.md` — 固定欄陰影
+- `../../tokens/elevation/elevation.spec.md` — drag ghost 陰影(`--elevation-200`;固定欄分界為 1px divider,無陰影)
 - `../Field/field-controls.spec.md` — cell editable 時的 Field Control 共用規則
 
 ## A11y 預設
 
-**ARIA / Pattern**:DataTable 是 composite tabular widget,**對齊 W3C ARIA Authoring Practices Guide `grid` pattern**(非 `radio-group`):
+**ARIA / Pattern**:DataTable 是 composite tabular widget,**對齊 W3C ARIA Authoring Practices Guide `grid` pattern**(非 `radio-group`——之前 boilerplate 從 RadioGroup spec 誤抄;DataTable 是 multi-row / multi-column composite,not single-choice selection group,a11y semantics 完全不同(grid vs radio-group)<!-- @benchmark-verified: 2026-05-18 D1 rewrite -->):
 
 - Root 套 `role="table"`(currently)或 `role="grid"`(future tier,when cell editing 普及)— 詳 [WAI-ARIA APG: grid](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) + [MDN grid role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/grid_role)
 - Column headers:以 `<div role="columnheader">` 顯式標記(本元件用 div + ARIA role,非語義 `<table>` — 見定位段;不渲染 `<th>` / `scope`)
@@ -513,11 +471,11 @@ DataTable 是 composite multi-section 元件,**不套 canonical 5**(Inspector /
 - 字 cell hover overlay action:overlay 為 absolute/fixed paint layer(`DataTableInteractionLayer`),trigger 目前**未**套 `aria-haspopup` / `aria-controls`(留待 future tier)
 
 **Keyboard 行為**(目前實作 — `tableKeyboardHandler`):
-- ↑↓←→:cell-to-cell navigation **僅 `spreadsheetMode` opt-in 時生效**(`spreadsheetMode && selectedCellId != null && editingCellId == null`);預設模式方向鍵無作用
-- Enter / F2:spreadsheet 模式下進 cell editing(cell 可編輯 + 非 boolean/url + 非 disabled 時)
+- ↑↓←→:cell-to-cell navigation **僅 `spreadsheetMode` opt-in 時生效**;selection 尚未建立時按方向鍵自動選取第一個 visible cell(鍵盤可直接進入 spreadsheet 導覽,無需滑鼠 click — 對齊 Excel / Google Sheets / AG Grid「focus grid → first cell active」,2026-07-05 D4 補);預設模式方向鍵無作用
+- Enter / F2:spreadsheet 模式下進 cell editing(cell 可編輯 + 非 boolean/url + 非 disabled 時);**Enter 確認後維持原格不下移**(2026-07-05 user 拍板;10 家實查:Excel 系 7 家下移、AG Grid 預設維持原格 — 採 AG Grid 派,數據 → `.claude/logs/deep-audit-2026-07-03/enter-commit-navigation-benchmark.json`;未來連續輸入需求可重議 opt-in);**edit 退出(commit / Esc)後 selection 還原至該 cell、焦點還給 table root**(editor unmount 後焦點掉到 body 才收回,不搶 user 點擊的新焦點 — 對齊 spreadsheet RFC Contract 11 + Excel / AG Grid,2026-07-05 D4 補)
 - Cmd/Ctrl+A:`mode="multi"` selection 時選全可見列(扣 disabled)
-- Esc:取消 editing(spreadsheet)/ 清 selection(selection mode)
-- Tab:進入表格後操作排序與勾選
+- Esc:取消 editing(spreadsheet)/ 清 selection(selection mode);**IME 組字中的 Enter / Esc 不觸發 commit / cancel**(cell editor 帶 `isComposing` guard,2026-07-05 D4 補 — 中文選字 Enter 不誤提交半截組字)
+- Tab:進入表格後操作排序與勾選;portal edit(`experimentalActiveEditorController`)中 Tab / Shift+Tab = commit 當前 draft + 移至下一個 editable cell 進 edit(2026-07-05 D4 補 commit — 原本換格丟 draft)
 
 > APG grid full keyboard model(Home/End、Ctrl+Home/End、PageUp/PageDown、roving cell action)為 `role="grid"` future tier 目標,**尚未實作**。
 
@@ -525,8 +483,6 @@ DataTable 是 composite multi-section 元件,**不套 canonical 5**(Inspector /
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
-**Why not radio-group**:之前 boilerplate 從 RadioGroup spec 誤抄。DataTable 是 multi-row / multi-column composite,not single-choice selection group;a11y semantics 完全不同(grid vs radio-group)。 <!-- @benchmark-verified: 2026-05-18 D1 rewrite -->
-
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
@@ -536,5 +492,6 @@ DataTable 是 composite multi-section 元件,**不套 canonical 5**(Inspector /
 - `circular-progress.spec.md`
 - `description-list.spec.md`
 - `opacity.spec.md`
+- `pagination.spec.md`
 - `scroll-area.spec.md`
 - `tree-view.spec.md`

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

@@ -603,10 +603,11 @@ export const InlineEdit: Story = {
  * 驗證點:
  *   - hover editable cell → 1px overlay 邊框 var(--border-hover)
  *   - sku(readonly)/ inStock(boolean)/ url(openAction)→ 不出現 hover overlay(Contract 15)
- *   - click 1 → cell selected(2px primary border outline)
+ *   - click 1 → cell selected(1px `--primary` border outline,`CELL_RING_STYLES.selected`)
  *   - click 2 / Enter / F2 → enter edit(portal Field, cell mode 不變)
- *   - Shift+click → range(focus = 2px primary outline + 內 cells `--primary-subtle` bg)
- *   - cell border-box 對齊(0.5px sub-pixel snap;dtCellGrid 4-edge inset divider 共軌)
+ *   - Shift+click → range(focus = 1px primary outline + 內 cells `--primary-subtle` bg)
+ *   - cell border-box 對齊(float coords 直接 pass-through 不 round / 不 snap,overlay outline
+ *     -1px 剛好壓 cell 邊線;dtCellGrid right-edge inset divider + row border-b 共軌)
  *   - Issue 6 viewport clip:H scroll cell out → overlay 被 panel ClipMask 裁切不溢出
  */
 export const InlineEditWithSpreadsheetOverlay: Story = {
@@ -1939,3 +1940,50 @@ export const RoadmapPerfBudget: Story = {
     )
   },
 }
+
+// ── L5 分頁(2026-07-06)─────────────────────────────────────────────────────
+
+type OrderRow = { id: string; orderNo: string; customer: string; amount: number; placedAt: string }
+
+// 128 筆訂單(電商後台真實規模;deterministic 生成,無 Math.random)
+const ORDER_ROWS: OrderRow[] = Array.from({ length: 128 }, (_, i) => ({
+  id: `order-${i + 1}`,
+  orderNo: `SO-2026-${String(1001 + i)}`,
+  customer: ['Acme Corp', 'Globex', 'Initech', 'Umbrella', 'Stark Industries', 'Wayne Enterprises'][i % 6],
+  amount: 1200 + (i * 137) % 8800,
+  placedAt: `2026-0${(i % 6) + 1}-${String((i % 27) + 1).padStart(2, '0')}`,
+}))
+
+const orderColumns: ColumnDef<OrderRow>[] = [
+  { accessorKey: 'orderNo', header: '訂單編號' },
+  { accessorKey: 'customer', header: '客戶' },
+  { accessorKey: 'amount', header: '金額', cell: ({ getValue }) => `$${(getValue() as number).toLocaleString()}` },
+  { accessorKey: 'placedAt', header: '成立日期' },
+]
+
+export const WithPagination: Story = {
+  name: '分頁',
+  render: () => (
+    <div className="mx-[var(--layout-space-loose)] my-[var(--layout-space-loose)] flex flex-col gap-8">
+      <div>
+        <p className="text-caption text-fg-muted mb-2">
+          預設形態:`pagination` 傳 true — 128 筆 / 每頁 20 = 7 頁,分頁列間距 tight、頁碼靠右
+          (spec「L5:分頁」canonical);與虛擬滾動互斥(分頁時 useVirtual 關閉)。
+        </p>
+        <DataTable columns={orderColumns} data={ORDER_ROWS} pagination getRowId={(row) => row.id} />
+      </div>
+      <div>
+        <p className="text-caption text-fg-muted mb-2">
+          完整形態:「共 N 筆」opt-in(showTotal)+ 每頁筆數 Select(pageSizeOptions)——
+          左資訊右頁碼 justify-between;換每頁筆數自動回第 1 頁;filter 縮小自動 clamp 當前頁。
+        </p>
+        <DataTable
+          columns={orderColumns}
+          data={ORDER_ROWS}
+          pagination={{ pageSize: 20, pageSizeOptions: [10, 20, 50], showTotal: true }}
+          getRowId={(row) => row.id}
+        />
+      </div>
+    </div>
+  ),
+}