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

package/src/components/DataTable/data-table-column-visibility-panel.tsx

@@ -10,7 +10,7 @@
  *   - Locked 欄位(`lockedIds`)— 顯 Lock icon,不可 toggle / 不可 drag
  *   - 可選 search filter(`searchable`,跨欄位 label match)
  *   - 可選 column drag reorder(`onColumnOrderChange` 傳 → 啟 DnD)
- *   - 可選 reset 按鈕(`onReset`,header 區 RotateCcw)
+ *   - 可選 reset 按鈕(`resettable: boolean` opt-in,header 區 RotateCcw;點擊 `onVisibilityChange({})` 還原全顯示,無獨立 onReset prop)
  *   - Bidirectional bulk toggle(footer button:全可見 → 全部隱藏 / 任一隱藏 → 顯示全部)
  *
  * **Why 抽 primitive**(per Issue 3 Rule-of-3):RoadmapAllInOne + WithBulkActions + 未來 product

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

@@ -1,6 +1,6 @@
 // @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.
 // same-row-mixed-allow: header chrome corner buttons(close)跟 row inline actions(trash)不在同 row
-// code-quality-allow: file-size — 2026-05-03 M21 retract:filter-value-picker.tsx(187 行 / 1 consumer)inline 回本檔。panel 從 505 → 687 行,進 transition zone 但未過 800 hard cap。等 inline filter UI 接入第 2 consumer 再考慮抽出。
+// code-quality-allow: file-size — 2026-05-03 M21 retract:filter-value-picker.tsx(187 行 / 1 consumer)inline 回本檔(505 → 687 行)。2026-07-14 deep-audit 誠實更新:現 822 行,**已過 800 hard cap** — 非 stale escape 留著;拆檔候選 = filter-value-picker 區段(等第 2 個 consumer 接入)+ nested-group renderer,屬結構 refactor 需獨立 branch 做 + 完整驗證,列入 file-size escalation 追蹤,禁再增量。
 import * as React from 'react'
 import { Plus, Trash2, X as XIcon, RotateCcw } from 'lucide-react'
 import type { ColumnDef } from '@tanstack/react-table'
@@ -439,6 +439,9 @@ function DataTableFilterPanelInner<TData>({
         field: prefilledColumnId,
         op: getDefaultOperator(colInfo.type),
         value: '',
+        // 2026-07-14 deep-audit fix:補 datePrecision(原漏 → datetime(includeTime=true)欄
+        // prefill 掉到 undefined=day 精度忽略 ms;對齊初始 add / changeField 路徑的 datePrecisionOf)
+        datePrecision: datePrecisionOf(colInfo),
       }
       if (value.mode === 'flat') {
         onChange({ ...value, children: [...value.children, cond] })

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

@@ -1,3 +1,4 @@
+// @internal — DS-internal 單元(viewport 覆蓋 paint layer,只被 data-table.tsx 內部消費);不隨 index.ts re-export 進 npm public surface。
 /**
  * DataTableInteractionLayer — Slice D Step 1A scaffold(per `.claude/planning/datatable-spreadsheet-rfc.md`)
  *
@@ -30,15 +31,16 @@ interface CellRect {
 interface DataTableInteractionLayerProps {
   /** Flag default false:不破現有 outline。enable 後 hover/editor 走 overlay。 */
   enabled: boolean
-  /** Container ref;layer absolute position 對 container origin */
+  /** Container ref;geometry source(getCellRect 由此 query cell DOM)。layer root 本身是
+   *  position:fixed inset:0 viewport-anchor(見 render),非 container-origin absolute */
   containerRef: React.RefObject<HTMLDivElement | null>
   /** Per Contract 15:`cellClickEntersEdit` predicate;hover overlay 顯示與否 */
   cellClickEntersEdit?: (cellId: CellId) => boolean
   /**
-   * Slice D Step 3 scaffold(2026-05-10):active editor cell id。null = 無 active editor。
-   * 當前只 render rect placeholder layer(z-index 3,higher than hover ring z-index 1)。
-   * Future:ActiveEditorHost portal active edit Field per Contract 8 「two paint owners」。
-   * Wire-up 走 codex Q-7 string-first canary(text cell first,picker types 漸進)。
+   * Active editor cell id。null = 無 active editor。
+   * 已接線(Slice D Step 5 完成,2026-07-14 docblock 對齊):activeEditorEnabled +
+   * activeEditorCellId + activeEditorRender 齊 → ActiveEditorHost(z 3)portal render
+   * 真 edit Field(per Contract 8「two paint owners」)。
    */
   activeEditorCellId?: CellId | null
   /**
@@ -55,12 +57,6 @@ interface DataTableInteractionLayerProps {
    * Layer renders solid border SelectionRect(per user「不要 dash 直接實的就好」)。
    */
   selectedCellId?: CellId | null
-  /**
-   * Slice D Step 4 range support(per user「應該支援 range」+ codex Q2.1 Airtable/AG Grid
-   * cite):range cell IDs from anchor↔focus rectangle。Layer renders bg-fill RangeRect
-   * (z 1,bg `--primary-subtle`)+ selection border on focus cell。
-   */
-  rangeCellIds?: CellId[]
   /**
    * Slice D Step 5(D.3 portal Field,2026-05-10 user 拍板「在乎完美乾淨」+ codex Q6.1
    * 撤回 defer):active editor render callback。當 activeEditorEnabled + activeEditorCellId
@@ -222,10 +218,11 @@ function useHoveredCell(
 }
 
 /**
- * Singleton interaction layer。
+ * Singleton interaction layer(全 sub-layer 已接線;2026-07-14 docblock 對齊實作)。
  *
- * Slice D Step 1A:HoverCellRect only。
- * Slice D Step 2/3/4:SelectionRect / ActiveEditorHost / RangeRect 漸進加入。
+ * 現況:HoverCellRect(z 1)+ SelectionRing(z 2)+ ActiveEditorHost(z 3,portal edit Field);
+ * range 視覺走 cell 自身 CSS `[data-range-cell]`(RangeRect / rangeCellIds prop 已 retire)。
+ * layer root = position:fixed inset:0 viewport-anchor,pointerEvents:none(僅 ActiveEditorHost 開 auto)。
  */
 export function DataTableInteractionLayer({
   enabled,
@@ -235,8 +232,6 @@ export function DataTableInteractionLayer({
   activeEditorEnabled = false,
   activeEditorRender,
   selectedCellId = null,
-  // rangeCellIds retired 2026-05-10(outer ring 已 retire,range visual 靠 cell-bg `[data-range-cell]`)
-  rangeCellIds: _rangeCellIds,
 }: DataTableInteractionLayerProps) {
   const hoveredCellId = useHoveredCell(containerRef, enabled)
   // 2026-05-10 RWD/scroll sync(per user mandate「所有 overlay 在各種 RWD 和捲動時都處在正確位置」):
@@ -264,7 +259,7 @@ export function DataTableInteractionLayer({
     ? getCellRect(containerRef.current, activeEditorCellId)
     : null
 
-  // Slice D Step 4(spreadsheet semantics):SelectionRect + RangeRect with viewport clip。
+  // Slice D Step 4(spreadsheet semantics):SelectionRing with viewport clip(RangeRect 已 retire — range 視覺走 CSS [data-range-cell])。
   const selectedGeo = enabled && selectedCellId != null
     ? getCellGeometry(containerRef.current, selectedCellId)
     : null
@@ -341,9 +336,10 @@ function toRelRect(cellRect: CellRect, clipRect: CellRect): CellRect {
 
 // ── Private primitives(per codex unified-ring-overlay-2026-05-10 Final A')──────
 //
-// 三個 private primitive 各自 own 一個 paint concern:
+// 三個 private primitive 各自 own 一個 paint concern(2026-07-14 對齊實作:CellRangeFill
+// 不存在 — range bg 走 cell 自身 CSS `[data-range-cell]`,非 layer 元件):
 //   1. CellRingOverlay  — outline ring(hover / selected / future focus / error)
-//   2. CellRangeFill    — bg fill(range cells in spreadsheet mode)
+//   2. ClipMask         — panel viewport 裁切 wrapper(Issue 6 partial-visibility)
 //   3. ActiveEditorHost — opaque host(portal Field edit)
 //
 // SSOT pattern(共 3 primitives):rect float pass-through + boxSizing:border-box +

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

@@ -1,7 +1,8 @@
 // @anatomy-rationale:
 //   SizeMatrix represented as RowHeightMatrix per row-density semantics —
-//     DataTable 的 size 不是字級放大而是 row-height tier(compact / cozy /
-//     comfortable),語意對應「掃描 vs 閱讀」資料密度而非元件大小。命名沿用
+//     DataTable 的 size 主軸是 row-height tier(compact / cozy /
+//     comfortable),語意對應「掃描 vs 閱讀」資料密度;lg 同時連動字級放大
+//     (sm/md → text-body / lg → text-body-lg,對齊 Field,SSOT fieldDisplayTextClass)。命名沿用
 //     Linear / Notion / Airtable 業界共識(row density,非 component size)。
 //   StateBehavior covered by ColorMatrix「Row 狀態色彩」段(default / hover /
 //     selected / disabled)+ Features「排序」段。Row 互動是 row-level
@@ -131,7 +132,7 @@ export const Inspector: Story = {
     bordered: { control: 'boolean', description: '外框(嵌入已帶框容器時可設 false 避免雙重邊框)' },
     pinnedLeft: { control: 'boolean', description: 'Pin 產品名稱欄到左側,橫向捲動時保持可見' },
     pinnedRight: { control: 'boolean', description: 'Pin 上架日期欄到右側' },
-    inlineEdit: { control: 'boolean', description: 'inline edit 視覺:cell 間加垂直分隔線(dtCellGrid)。Select 欄 chevron 由 column meta.editable 控制(showDisplayEndIcon),非本 prop' },
+    inlineEdit: { control: 'boolean', description: 'inline edit 視覺:cell 間加垂直分隔線(dtCellGrid)。display 態零恆顯 chevron(2026-07-08 A 案,editable affordance = hover outline);edit 態才有控件 chrome' },
     height: {
       control: 'select',
       options: ['auto', '300px'],
@@ -171,8 +172,9 @@ export const ColumnTypes: Story = {
     const columns = [
       col.accessor('name', { header: 'text', meta: { type: 'string', width: 200 } }),
       col.accessor('price', { header: 'currency', meta: { type: 'currency', prefix: '$', width: 120 } }),
-      col.accessor('stock', { header: 'select(Tag)', meta: { type: 'select', options: STATUS_OPTIONS, width: 140 } }),
-      col.accessor('available', { header: 'boolean(✓/—)', meta: { type: 'boolean', width: 100 } }),
+      // display:'tag' opt-in 讓 demo 與 header「select(Tag)」名實相符(SelectCell 預設 plain 純文字)
+      col.accessor('stock', { header: 'select(Tag)', meta: { type: 'select', options: STATUS_OPTIONS, width: 140, display: 'tag' } }),
+      col.accessor('available', { header: 'boolean(勾選框)', meta: { type: 'boolean', width: 100 } }),
       col.accessor('launchDate', { header: 'date', meta: { type: 'date', width: 140 } }),
     ]
 
@@ -194,7 +196,7 @@ export const ColumnTypes: Story = {
                 <tr><Td mono>number</Td><Td mono>{`<NumberInput mode="display">`}</Td><Td>right</Td><Td>數量、年齡</Td></tr>
                 <tr><Td mono>currency</Td><Td mono>{`<NumberInput mode="display">`}(+ prefix)</Td><Td>right</Td><Td>金額、價格</Td></tr>
                 <tr><Td mono>date</Td><Td mono>{`<DatePicker mode="display">`}</Td><Td>left</Td><Td>日期、時間戳</Td></tr>
-                <tr><Td mono>boolean</Td><Td mono>{`<Checkbox mode="display">`}(✓ / —)</Td><Td>left</Td><Td>啟用 / 可見</Td></tr>
+                <tr><Td mono>boolean</Td><Td mono>{`<Checkbox mode="display">`}(勾 / 叉 icon)</Td><Td>left</Td><Td>啟用 / 可見</Td></tr>
                 <tr><Td mono>select</Td><Td mono>{`<Select mode="display">`}</Td><Td>left</Td><Td>狀態、類別</Td></tr>
                 <tr><Td mono>multiSelect</Td><Td mono>{`<Combobox mode="display">`}</Td><Td>left</Td><Td>多選 tags</Td></tr>
                 <tr><Td mono>person</Td><Td mono>PersonDisplay / MultiPersonDisplay</Td><Td>left</Td><Td>指派者、reviewer</Td></tr>
@@ -202,7 +204,7 @@ export const ColumnTypes: Story = {
               </tbody>
             </table>
           </div>
-          <p className="text-footnote text-fg-muted mt-3">擴充新 type:在 `column-types.ts` 註冊 `renderDisplay` + `align`,自動跟所有 DataTable 整合</p>
+          <p className="text-footnote text-fg-muted mt-3">擴充新 type:在 `cell-registry.tsx` 的 `cellRegistry` map 註冊對應 Cell component(display/edit 渲染 SSOT);`column-types.ts` 只設 `align` / default metadata。兩處對齊後自動跟所有 DataTable 整合</p>
         </div>
       </div>
     )
@@ -260,8 +262,8 @@ export const AlignmentRule: Story = {
     return (
       <div className="flex flex-col gap-8">
         <div>
-          <H3>Column type 決定對齊(由 column-types.ts 定義,不讓 consumer 手動設)</H3>
-          <Desc>數字靠右方便縱向比較位數(Excel / 會計軟體 / 財務系統共識);文字靠左方便閱讀;boolean 靠左跟其他文字欄一致,維持掃視時的左緣節奏。Consumer 不需要設 `align`,column type 就決定了。</Desc>
+          <H3>Column type 提供對齊預設(column-types.ts 定義),consumer 可用 meta.align 覆寫</H3>
+          <Desc>數字靠右方便縱向比較位數(Excel / 會計軟體 / 財務系統共識);文字靠左方便閱讀;boolean 靠左跟其他文字欄一致,維持掃視時的左緣節奏。Consumer 通常不需要設 `align`——column type 已給預設;需要時仍可用 `meta.align` 在 column 層級覆寫。</Desc>
           <DataTable columns={columns} data={SAMPLE_DATA} height="auto" />
         </div>
 
@@ -273,7 +275,7 @@ export const AlignmentRule: Story = {
               <tbody>
                 <tr><Td>text / select / person / date / link</Td><Td mono>left</Td><Td>閱讀從左到右</Td></tr>
                 <tr><Td>number / currency</Td><Td mono>right</Td><Td>縱向比較位數(小數點縱向對齊)</Td></tr>
-                <tr><Td>boolean(✓ / —)</Td><Td mono>left</Td><Td>跟其他文字欄一致靠左,維持掃視時的左緣節奏</Td></tr>
+                <tr><Td>boolean(勾 / 叉 icon)</Td><Td mono>left</Td><Td>跟其他文字欄一致靠左,維持掃視時的左緣節奏</Td></tr>
                 <tr><Td>actions(在 cell 內的按鈕)</Td><Td mono>right</Td><Td>動線尾端,不干擾資料掃視</Td></tr>
               </tbody>
             </table>
@@ -437,10 +439,10 @@ export const ColorMatrix: Story = {
             </thead>
             <tbody>
               <tr><Td mono>text / date / number / currency</Td><Td><TokenCell token="--foreground" /></Td></tr>
-              <tr><Td mono>select(Tag)</Td><Td>Tag 的 variant 色(green / yellow / red / blue…)</Td></tr>
+              <tr><Td mono>select</Td><Td>預設 plain 純文字 foreground;`meta.display='tag'` opt-in 才走 Tag 的 variant 色(green / yellow / red / blue…)</Td></tr>
               <tr><Td mono>person</Td><Td>Avatar + foreground 文字</Td></tr>
               <tr><Td mono>link</Td><Td><TokenCell token="--primary" /></Td></tr>
-              <tr><Td mono>boolean</Td><Td><TokenCell token="--fg-secondary" display="— / ✓ 均用 fg-secondary" /></Td></tr>
+              <tr><Td mono>boolean</Td><Td>naked Checkbox(true = <TokenCell token="--primary" display="primary 底白勾" /> / false = 空框 <TokenCell token="--border" />),非 X / Check icon</Td></tr>
             </tbody>
           </table>
         </div>
@@ -513,7 +515,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"DataTable 用一般 div 搭配表格語意標記,而非原生 table 元素——因為虛擬捲動需要絕對定位每一列,而 table 的佈局模型做不到。輔助技術(螢幕報讀器)會把它當成表格朗讀。\n\n  表格語意  :最外層標記為表格、每一列標記為列、每一格標記為儲存格,表頭那一格標記為欄位標題。\n\n  排序  :可排序的表頭會標示目前的排序方向(升冪 / 降冪 / 未排序),報讀器讀得出來。\n\n  選取  :每一列的勾選框都有說明文字(由使用方傳入,沒傳就用「選取此列」),全選框的說明文字是「全選可見列」。\n\n  鍵盤  :一般表格模式下,用 Tab 進入表格後可操作排序與勾選;方向鍵在儲存格之間移動是試算表模式(spreadsheetMode)才開啟的功能,不是預設。列上的更多操作都收進右側的「更多」選單,確保不用滑鼠也能用。\n\n  焦點  :鍵盤聚焦時顯示清楚的外框,與整個設計系統的聚焦樣式一致。\n\n  驗證  :Storybook 無障礙檢查面板應該沒有嚴重問題;全程鍵盤可操作,不必用到滑鼠;文字對比度達到無障礙標準。"}</p>
+      <p className="whitespace-pre-line">{"DataTable 用一般 div 搭配表格語意標記,而非原生 table 元素——因為虛擬捲動需要絕對定位每一列,而 table 的佈局模型做不到。輔助技術(螢幕報讀器)會把它當成表格朗讀。\n\n  表格語意  :最外層標記為表格、每一列標記為列、每一格標記為儲存格,表頭那一格標記為欄位標題。\n\n  排序  :可排序的表頭會標示目前的排序方向(升冪 / 降冪 / 未排序),報讀器讀得出來。\n\n  選取  :每一列的勾選框都有說明文字(由使用方傳入,沒傳就用「選取此列」),全選框的說明文字是「全選可見列」。\n\n  鍵盤  :一般表格模式下,用 Tab 進入表格後可操作排序與勾選;方向鍵在儲存格之間移動是試算表模式(spreadsheetMode)才開啟的功能,不是預設。列上的更多操作(`rowActions` 為使用方提供的 callback,DataTable 不代管收納)建議在 3 個以上時由使用方自行收進右側的「更多」選單,以確保不用滑鼠也能操作全部動作。\n\n  焦點  :一般元件(排序鈕 / 勾選框)鍵盤聚焦時顯示清楚外框,與設計系統聚焦樣式一致;啟用選取 / 試算表模式時,表格本身可被 Tab 聚焦,焦點以「選取儲存格」的方框呈現(表格外層刻意不另畫外框),初次 Tab 尚未選取儲存格時焦點落在表格容器。\n\n  驗證  :Storybook 無障礙檢查面板應該沒有嚴重問題;全程鍵盤可操作,不必用到滑鼠;文字對比度達到無障礙標準。"}</p>
     </div>
   ),
 }

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

@@ -93,10 +93,10 @@ export const UsageGuidance: Story = {
       </Rule>
 
       <Rule
-        title="❌ 不用 DataTable 表達階層結構（部門 / 資料夾）"
-        note="DataTable 是平面 row。階層結構（可展開收合）改用 TreeView。Notion 的資料庫可以 expand row，但階層樹用 TreeView"
+        title="❌ 不用 DataTable 表達深層階層結構（部門 / 資料夾 tree）"
+        note="DataTable 支援淺層 nested-rows（展開子列，如任務 / 子任務）；但深層多階縮排 + 大量節點的 folder / dept tree 語意仍屬 TreeView。Notion 的資料庫可以 expand row，但側欄階層樹用 TreeView"
       >
-        <Label warn>階層結構用 TreeView，支援無限深度展開 / 收合</Label>
+        <Label warn>深層階層樹用 TreeView（無限深度展開 / 收合）；淺層子列 DataTable 可用</Label>
       </Rule>
 
       <Rule
@@ -107,10 +107,10 @@ export const UsageGuidance: Story = {
       </Rule>
 
       <Rule
-        title="❌ 不用 DataTable 做試算表（公式、跨 cell 選取）"
-        note="DataTable 是資料展示，不支援 Excel 功能。需要試算表能力 → AG Grid Enterprise / Handsontable。Airtable 確實像表，但 DataTable 不是設計來做這個"
+        title="❌ 不用 DataTable 做公式 / cell-level 計算"
+        note="DataTable 的 spreadsheetMode 支援跨 cell 選取 / Shift 矩形範圍 / 方向鍵導覽 / cell 編輯；但公式與 cell-level 計算超出範圍 → AG Grid Enterprise / Handsontable。Airtable 確實像表，但 DataTable 不是設計來做這個"
       >
-        <Label warn>試算表功能用專門 library，不往 DataTable 塞</Label>
+        <Label warn>公式 / 計算用專門 library，不往 DataTable 塞；跨 cell 選取 / 編輯用 spreadsheetMode</Label>
       </Rule>
     </div>
     </div>
@@ -140,14 +140,14 @@ export const ColumnTypeRule: Story = {
 
         <Rule
           title="❌ 手寫 cell render 自訂格式化"
-          note="每 column 自己寫 `cell: (info) => ...` 會繞過 `mode='display'` 系統——**格式化邏輯會漂移**。一個 table 的 price 顯示「$2,490」,另一個 table 的 price 顯示「2490」,一個 boolean 顯示「✓」,另一個 boolean 顯示「是」——整個系統 format 失去一致性"
+          note="每 column 自己寫 `cell: (info) => ...` 會繞過 `mode='display'` 系統——**格式化邏輯會漂移**。一個 table 的 price 顯示「$2,490」,另一個 table 的 price 顯示「2490」,一個 boolean 顯示勾 icon,另一個 boolean 顯示「是」——整個系統 format 失去一致性"
         >
           <Label warn>除非真的需要 `mode='display'` 無法提供的客製視覺,否則一律走 meta.type 系統。客製化時完全跳過 type 讓 display 渲染不要干預</Label>
         </Rule>
 
         <Rule
-          title="擴充新 type:到 column-types.ts 註冊"
-          note="新增資料類型(如 `percentage`、`relative-time`)在 `column-types.ts` 註冊 renderDisplay + align,自動跟所有 DataTable 整合。不在單一 table 硬寫"
+          title="擴充新 type:到 cell-registry.tsx 註冊"
+          note="新增資料類型(如 `percentage`、`relative-time`)在 `cell-registry.tsx` 的 `cellRegistry` map 註冊對應 Cell component(display/edit 渲染 SSOT);`column-types.ts` 只設 align / default metadata。兩處對齊後自動跟所有 DataTable 整合,不在單一 table 硬寫"
         >
           <Label>讓 column type 系統成為 single source of truth,所有 table 受惠同一次更新</Label>
         </Rule>

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

@@ -44,10 +44,10 @@ DataTable 是基於 TanStack Table 的資料表格元件，提供排序、篩選
 | 場景 | 改用 | 原因 |
 |------|------|------|
 | 唯讀的 key-value 展示（profile 屬性列表）| `DescriptionList` | DataTable 是多 row 集合，DescriptionList 是單一實體的屬性 |
-| 階層結構（部門 / 資料夾 tree）| `TreeView` | DataTable 是平面 row，不支援階層展開收合 |
+| 深層階層結構（部門 / 資料夾 tree）| `TreeView` | DataTable 支援淺層 nested-rows（L4 展開子列），但深層多階縮排 + 大量節點的 folder/dept tree 語意仍屬 TreeView |
 | 卡片式瀏覽（圖文並列）| 自訂 grid / list | Table 是密集 row，不適合大圖 |
 | 只有 2-3 筆且不需互動 | 直接 `<dl>` 或自訂 layout | DataTable 的 overhead 對小資料集過度工程 |
-| 試算表（公式 / 跨 cell 選取）| 超出範圍，用專門試算表 library | DataTable 不做 cell-level 計算 |
+| 試算表（公式 / cell-level 計算）| 超出範圍，用專門試算表 library | DataTable 的 `spreadsheetMode` 支援跨 cell 選取 / Shift 矩形範圍 / 方向鍵導覽 / cell 編輯,但不做公式或 cell-level 計算 |
 | 需要複雜群組 header + 合併 cell | 自訂或 TanStack 原始 API | DataTable 對 header group 的抽象層有限 |
 
 ---
@@ -139,7 +139,7 @@ Table 層級的模式切換，不是 column 層級。跟 AG Grid / Airtable 的
 
 ### 七、Column Type
 
-**Column type 是資料行為的預設合約。** 指定 type 自動獲得對齊 / 渲染 / 排序 / 篩選行為,可在 column 層級覆寫。Header 對齊永遠跟該欄 body cell 一致。
+**Column type 是資料行為的預設合約。** 指定 type 自動獲得對齊 / 渲染 / 排序 / 篩選行為,可在 column 層級覆寫。Header 對齊永遠跟該欄 body cell 一致。select/multiSelect 的 `meta.options` 消費 Select 的完整 `SelectOption` schema(M30 wrapper-extends-primitive;含 icon / iconClassName / description),`meta.selectedItemRenderer` 轉發 Select 同名 API 供 status 類彩色 cell(2026-07-08 補——原 `{value,label}` 窄型別 = 假 SSOT,WM 被迫手刻 bare trigger 實證)。
 
 ### 八、Row 狀態
 
@@ -154,7 +154,7 @@ Table 層級的模式切換，不是 column 層級。跟 AG Grid / Airtable 的
 
 **世界級對照**: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";dropdown 包含所有操作,確保鍵盤可存取全部)。**Header/body 寬度同步**:header 渲染 invisible buttons 佔位(同 size="xs"),確保 header 和 body 的 right region 同寬。
+**收納邏輯(consumer 自建)**:`rowActions` 是 raw callback `(row)=>ReactNode`,DataTable 原樣渲染回傳內容,**不代管計數 / 不自動 MoreVertical 收納**。建議 consumer 自行實作:1-2 個 → icon buttons 並排(全 size="xs");3+ → 前 1-2 個 inline + MoreVertical dropdown(全 size="xs";dropdown 包含所有操作,確保鍵盤可存取全部)。**Header/body 寬度同步**(DataTable 代管):header 渲染同一 `rowActions` 輸出但設為 invisible 佔位,確保 header 和 body 的 right region 同寬。
 
 ### 九之二、Cell action primitive 分類(2026-04-29 codified)
 
@@ -164,7 +164,7 @@ SSOT → `patterns/element-anatomy/inline-action.spec.md`「Real case 表」+ Pr
 |------|-----------|
 | Header cell internal(sort / ⌄ menu / filter funnel / pin)| `ItemInlineActionButton` `size="md"`(對齊 AG Grid / Material / Airtable / Notion / Polaris) | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 | **Multi-sort header(≥2 columns sorted)** | **隱藏 header arrow + 取消排序 dropdown option**(K7,2026-05-04)— 無 order 編號的單個 arrow 在 multi-sort 是 partial info → 反而混淆;user 走 SortManager panel 看完整 priority(SSOT)。0/1 sort 仍秀 arrow 完整資訊。理由:現行 DS 不顯 sort order 編號,跟 Airtable / Linear / Atlassian / Carbon 純箭頭派一致;multi-sort 時這派需 SortManager fallback(world-class 共識) |
-| Body cell internal(display endAction / clear / edit indicator)| Field family endAction(自動繼承) |
+| Body cell internal(display endAction / clear / edit indicator)| Field family endAction(自動繼承)。**Display 態零恆顯型別 icon(2026-07-08 A 案)**:editable affordance = hover outline(SSOT → field.spec.md L4/L6,`nakedCellEditableDisplayHover`);boolean = live Checkbox(AG Grid 同);url = hover Pencil(click-opens-link 與 edit 衝突的功能性入口,非型別 indicator)。**cell 空值 = 全空白**(2026-07-08 B 案,SSOT → field-controls.spec.md「null / undefined 值」surface 分流表) |
 | Row dedicated action column | Button `xs iconOnly` 24px(見「九、Row Actions」) |
 | Toolbar | Button(action-bar 共識) |
 
@@ -213,13 +213,13 @@ type DataTableSelection =
 selection?: string[] | DataTableSelection         // controlled;傳 string[] = include shorthand(向後相容)
 defaultSelection?: string[] | DataTableSelection  // uncontrolled
 onSelectionChange?: (next: DataTableSelection) => void  // 一律 emit union
-totalCount?: number                   // 全集筆數 M(server-side / filter 後);all 模式計數用
+// (無 totalCount prop — 全集筆數 M 由 consumer 自持;2026-07-13 D1 拍板移除 DS 內零消費 no-op prop)
 selectable?: boolean | 'single' | 'multi'  // default false(不啟用);true 等同 'multi';single 永遠 include
 isRowSelectable?: (row: TData) => boolean
 preserveSelectionOnFilter?: boolean   // default false
 ```
 
-對齊 `useControllableState` idiom(Field / Switch / Checkbox 已用)+ MUI X DataGrid v8 `rowSelectionModel { type:'include'|'exclude', ids }` / AG Grid `selectAll + toggledNodes` 反向選取共識。**計數(consumer)**:`mode==='all' ? totalCount − excluded.length : ids.length`。**向後相容**:傳 `string[]` 自動正規化為 `{ mode:'include' }`;但 `onSelectionChange` 一律 emit union(consumer 讀取端需處理兩 mode)。
+對齊 `useControllableState` idiom(Field / Switch / Checkbox 已用)+ MUI X DataGrid v8 `rowSelectionModel { type:'include'|'exclude', ids }` / AG Grid `selectAll + toggledNodes` 反向選取共識。**計數(consumer)**:`mode==='all' ? M − excluded.length : ids.length`(M = consumer 自持的全集筆數,DataTable 不收 totalCount prop)。**向後相容**:傳 `string[]` 自動正規化為 `{ mode:'include' }`;但 `onSelectionChange` 一律 emit union(consumer 讀取端需處理兩 mode)。
 
 ### 二、Checkbox column
 
@@ -235,7 +235,7 @@ preserveSelectionOnFilter?: boolean   // default false
 1. Header checkbox click(none → all)→ 選**目前可見** rows(filter 後 visible-only)= `{ mode:'include', ids:[…visible] }`
 2. 全頁可見已選 → BulkActionBar hint:「已選取本頁 N 個。**點此選取全部 M 個**」
 3. 點 hint → consumer `setSelection({ mode:'all', excluded:[] })` 擴 dataset 全選,hint 改:「已選取全部 M 個。**清除選取項目**」
-4. **反向選取(inverted)**:all 模式下取消勾選某幾筆 → 加進 `excluded`(`選取 = 全集 − excluded`);再勾回 → 移出 `excluded`。對 10k 筆只載 50 筆**不需列舉其餘 ID**,任意 toggle 順序封閉、O(1)。count = `totalCount − excluded.length`,hint 顯示「已選取全部 M 個(排除 K 個)」。
+4. **反向選取(inverted)**:all 模式下取消勾選某幾筆 → 加進 `excluded`(`選取 = 全集 − excluded`);再勾回 → 移出 `excluded`。對 10k 筆只載 50 筆**不需列舉其餘 ID**,任意 toggle 順序封閉、O(1)。count = `M − excluded.length`(M = consumer 自持全集筆數),hint 顯示「已選取全部 M 個(排除 K 個)」。
 
 不**一鍵**直接擴 dataset(避免誤觸大量資料,必先 2-step);擴選後的反向扣除由 inverted 模型自動處理。
 
@@ -255,7 +255,7 @@ preserveSelectionOnFilter?: boolean   // default false
 ### 六、Selection × filter / sort 互動
 
 - **`include` 模式**:filter 套用 → filtered-out 的 selected rows 預設清掉(對齊 Material / AG Grid / Polaris / GitHub / Gmail consensus) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **`all`(反向)模式**:語意 = 「全部**符合當前 filter**的列 − excluded」→ filter 變動時 selection set 隨 filter **自然重算**(M 跟著變),`excluded` 保留不清(被 filter 掉的 excluded 列無害,回到該 filter 時仍排除);**不**套用上面的 include-mode 清除。consumer 計數用更新後的 `totalCount`。
+- **`all`(反向)模式**:語意 = 「全部**符合當前 filter**的列 − excluded」→ filter 變動時 selection set 隨 filter **自然重算**(M 跟著變),`excluded` 保留不清(被 filter 掉的 excluded 列無害,回到該 filter 時仍排除);**不**套用上面的 include-mode 清除。consumer 計數用更新後的全集筆數 M(consumer 自持)。
 - **opt-in `preserveSelectionOnFilter={true}`**(僅 include 模式)→ 給 productivity scope(Linear / Airtable 用法),保留 hidden selected,BulkActionBar 顯示「{visible} selected ({hidden} hidden by filter)」
 - sort 套用 → selection 全保留(sort 不影響可見性,兩 mode 同)
 
@@ -265,7 +265,7 @@ preserveSelectionOnFilter?: boolean   // default false
 
 ### 八、a11y 預設
 
-- 每個 row checkbox 必有 `aria-label`:consumer 提供 `getRowAriaLabel?: (row) => string`,fallback `"Select row"`
+- 每個 row checkbox 必有 `aria-label`:consumer 提供 `getRowAriaLabel?: (row) => string`,fallback `'選取此列'`
 - header checkbox `aria-label="全選可見列"`
 - 鍵盤:`Space` toggle / `Shift+Space` 擴 range / `Cmd/Ctrl+A` 選全可見 / `Esc` clear
 - Selection 變更可選 `aria-live="polite"` 通知(consumer-implemented)
@@ -357,6 +357,17 @@ 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)
 
+### Inline create row(表格底部「+ 新增」列)— 只定義 idle 態(2026-07-08 WM 戰役 codify,user 拍板)
+
+**點擊後的編輯內容 consumer 自組**(常被客製,不 canonical 化、不加 DS API):TanStack headless 無此 feature(https://tanstack.com/table/v8/docs/guide/custom-features)、AG Grid 無內建(官方 blog 教 pinned row DIY:https://blog.ag-grid.com/add-new-rows-using-a-pinned-row-at-the-top-of-the-grid/)、Ant ProComponents 只定義 trigger 列。**可定義的只有尚未點擊的 idle 列**,幾何全消費既有 token(零新值):
+
+- **高度** = `h-table-row-{size}`(與 data row 精確同高 — 上方「三 region row 精確同高」延伸到此列)
+- **左 padding** = `--table-cell-px`,「+ icon + 文字」對齊**第一資料欄**內容起點(啟 selection / drag 系統欄時同樣對齊第一資料欄,Notion / Airtable 同)
+- **Typography** = cell 同字級(`fieldDisplayTextClass(size)`)+ `text-fg-muted`(placeholder 語感);Plus icon 同 `fg-muted`
+- **Hover** = 整列 `neutral-hover` + cursor-pointer,**整列可點**(hit-target 對齊 L2「整 cell 區可點擊」)
+- **點擊 → inline**(不強制開 dialog;欄位複雜的 create 另走 Dialog 可並存);建議行為(非契約):Enter 提交後保持編輯態連續新增(Jira inline create idiom)、Esc 還原 idle 列
+- **拒絕**:Ant 式全寬 dashed 按鈕(表單語境 idiom,dashed 不在 DS 視覺語言);idle 列是 row 形(Notion「+ New」/ Airtable plus row / Asana「Add task…」line 資料庫工具共識)
+
 ### 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。例外:autoRowHeight string cell 的 edit 是 `Textarea` — Enter 換行、`Cmd/Ctrl+Enter` commit(blur 同 commit)。
@@ -369,7 +380,16 @@ ValueShape ↔ DS picker 對照(canonical 2026-05-02):
 | select / multiSelect | click cell | `<Select>` / `<Combobox>` |
 | person / multiPerson | click cell | `<PeoplePicker variant="naked">`(選人 picker) |
 | **boolean** | direct toggle | `<Checkbox>` 無 mode 切換 |
-| **url** | **hover cell → Pencil 按鈕(xs iconOnly tertiary)→ click** | `<Input>`(read 永遠是連結;cell click 走 anchor 開連結,**不**進 edit)|
+| **url** | **hover cell → Pencil 按鈕(xs iconOnly tertiary)→ click** | `<Input>`(read 永遠是連結;cell click 走 anchor 開連結,**不**進 edit)— 屬下方「navigate-valued cell 通用類別」|
+
+### Navigate-valued cell 通用類別(2026-07-08 user 拍板 codify — 原 url 專屬條文升級)
+
+**定義**:凡「點值的主行為 = 導航/開啟而非編輯」的型別(url;未來 parent / email / file / relation 同類),一律繼承四條 — 新型別只在上表登記一行,其餘全繼承,禁逐型別重刻:
+
+1. **排除 click-to-edit 與 hover outline**(code gate `data-table.tsx` editable-click 判斷排除該型別 — 此前只活在 code,本段為條文 SSOT):值可點 = click 屬導航,cell 不再是「點擊進 edit」目標,hover outline(field.spec.md L4)一併不套
+2. **排除 Enter / F2 進 edit**(下方鍵盤段「非 boolean/url」既有規則,類別化後隨表繼承)
+3. **唯一 edit affordance = hover Pencil**(xs iconOnly tertiary,`opacity-0 group-hover/cell:opacity-100`,onClick `stopPropagation` + `onRequestEdit`)— 對齊 AG Grid 官方三件套(`suppressClickEdit` + 「including a button in your cell renderer」+ `startEditingCell()`,https://www.ag-grid.com/react-data-grid/cell-editing-start-stop/)+ Jira hover-pencil + Notion title cell hover-OPEN 鏡像;Atlaskit target-tag 分流(點 `<a>` 導航、點空白區編輯)為次選已評估不採(與 hover-outline 統一 affordance 衝突)
+4. **edit 觸發後 = 一般 field 行為契約**:Pencil 只負責「進入 edit」一步;進入後 autoFocus 進輸入、Esc 取消、Enter/blur commit、驗證時機、focus 樣式全部回歸 field-controls edit-mode canonical,與其他型別 cell edit 零特例。若 edit 態控件與 form 場景不同(url 用 plain `<Input>` 非 LinkInput — LinkInput edit 預設顯 link 態,cell 需直接輸入),**必在上表該行寫明 documented 例外 + rationale**,禁只留 code 註解
 
 ### Nested rows — forward TanStack
 
@@ -407,7 +427,7 @@ Row drag + column reorder + TreeView 共用 `lib/drag-visual.ts`:source `opacity
 - **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 全集數,語意不同)
+- **`total` 數源** = `getPrePaginationRowModel().rows.length`(filter 後全集)——**不是** selection all-mode 的 server-side 全集數 M(那由 consumer 自持,語意不同)
 - filter / data 縮小時自動 clamp 當前頁(對齊 MUI X);`isEmpty` 時分頁列整條不渲染(Empty 已渲染)
 
 **與虛擬滾動互斥**:啟用分頁 → `useVirtual` 強制關閉——TanStack 官方定位兩者為互斥替代策略(分頁 = 每頁固定筆數主動換頁;虛擬滾動 = 連續滾動只渲可視列)。分頁時無虛擬化保護,建議 `pageSize ≤ 100`。

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

@@ -131,13 +131,9 @@ type Story = StoryObj
 // Anatomy 是 type-system structural canonical home(用 Product col helper 對齊其他 anatomy 範例);
 // 本 showcase 版用 custom `TypeDemo` interface,不對齊 anatomy 通用 type → noise。Retire showcase 版,anatomy 保留。
 
-/* ── 數字靠右對齊 ── */
-export const NumberAlignment: Story = {
-  name: '數字靠右對齊',
-  render: () => (
-    <DataTable columns={columnsWithPrice} data={sampleData} height="auto" />
-  ),
-}
+// Retired 2026-07-14 audit Dim 24:`NumberAlignment` 跟 anatomy.stories.tsx AlignmentRule 重複
+// (同「數字/金額靠右、文字靠左」規則,anatomy 版含完整 rationale Desc + column type 對照)。
+// Alignment 規則 canonical home = anatomy `AlignmentRule`;showcase 版無額外內容 → retire(earn-existence 2-test 雙 NO)。
 
 /* ── Column resize(2026-05-06 v11):table 層級開關 + handle hover 變色 ── */
 export const ColumnResize: Story = {
@@ -209,11 +205,11 @@ export const ColumnReorder: Story = {
     return (
       <div className="flex flex-col gap-3 max-w-5xl">
         <p className="text-caption text-fg-muted">
-          enableColumnReorder=true:hover header → grab cursor;拖曳期間 DragOverlay portal 顯示 ghost,
-          target column 邊緣顯 drop indicator(before/after 由 cursor 位置判定)。
+          開啟欄位重排(enableColumnReorder)後,拖住欄標題即可移動整欄:拖曳中欄位以半透明
+          浮影跟著游標,目標欄的左或右邊緣會出現落點提示線(依游標位置判定放在前或後)。
           <br />
-          - <strong>SKU 鎖定</strong>(<code>meta.locked=true</code>):無 grab cursor、被拖過不顯 drop
-          indicator(Notion primary column pattern)
+          - <strong>SKU 鎖定</strong>(<code>meta.locked=true</code>):不可拖曳,也不會成為落點
+          (對照 Notion 的主欄固定做法)
           <br />
           - System columns(__select__)永遠鎖
           <br />
@@ -830,8 +826,11 @@ export const NestedRows: Story = {
     )
     return (
       <div>
+        {/* 實作:forward TanStack getSubRows;縮排共用 --tree-indent-{sm,md,lg} token(跨 TreeView
+            設計語言);chevron click stopPropagation 不觸發 row select。 */}
         <p className="text-caption text-fg-muted mb-3">
-          forward TanStack <code>getSubRows</code> + 共用 token <code>--tree-indent-{'{sm,md,lg}'}</code>(跨 TreeView 設計語言)。Click chevron 展/收;chevron click stopPropagation 不 fire row select。
+          樹狀表格:點列首的三角形展開 / 收合子任務,子任務逐層縮排(與 TreeView 同一套縮排節奏);
+          點三角形只切換展開,不會順帶選取整列。
         </p>
         <DataTable
           columns={taskColumns}
@@ -1071,7 +1070,6 @@ export const WithBulkActions: Story = {
             selectable
             selection={selection}
             onSelectionChange={setSelection}
-            totalCount={TOTAL}
             columnVisibility={columnVisibility}
             onColumnVisibilityChange={setColumnVisibility}
             getRowId={(row) => row.sku}
@@ -1468,8 +1466,8 @@ export const RowDragInteractive: Story = {
       <div className="flex flex-col gap-3 max-w-3xl">
         <p className="text-caption text-fg-muted">
           handle 浮在 row 左緣（不佔 column 空間，Jira 設計準則）。pinned-left（SKU）+ pinned-right（Updated）+
-          center 中段欄。拖曳時 source 列留在原位（壓住視覺），2px 主色 drop indicator 跨三個 region
-          同步標示落點（per-region <code>useDraggable</code> / <code>useDroppable</code>，不 auto-shift）。
+          center 中段欄。拖曳時 source 列留在原位（半透明壓住視覺），2px 主色落點提示線在左固定欄、
+          中段、右固定欄三區同步標出，其他列不會先行讓位。
         </p>
         <DataTable
           columns={columnsWithPrice}
@@ -1515,9 +1513,10 @@ export const RowDragWithVirtualization: Story = {
     }
     return (
       <div className="flex flex-col gap-3 max-w-3xl">
+        {/* 實作(v3):enableRowDrag 自動拉高 overscan ≥ 5;drag 期間 freeze measureElement;
+            snapToCursorModifier 讓 ghost 對齊游標(不鎖軸)— 三者合修「拖曳 + 捲動錯位」。 */}
         <p className="text-caption text-fg-muted">
-          200 列 + 虛擬捲動。v3 修正:enableRowDrag 自動拉高 overscan ≥ 5、drag 期間 freeze
-          measureElement、snapToCursorModifier ghost 對齊游標（不鎖軸）— 拖曳 + 持續往下捲不再錯位。
+          200 列 + 虛擬捲動:拖住一列往下捲動,浮影一路跟著游標,落點在長清單任何位置都能正確對齊。
         </p>
         <DataTable
           columns={baseColumns}