@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.85

package/src/components/DataTable/data-table-filter-value-picker.tsx

@@ -0,0 +1,237 @@
+// @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(2026-07-14 自 data-table-filter-panel.tsx 拆檔搬移,原檔級 escape 隨段落帶入)。
+// @internal — DS-internal 單元(FilterValuePicker value-picker switcher,只被
+// data-table-filter-group.tsx FilterRow 消費);不隨 index.ts re-export 進 npm public surface。
+// ────────────────────────────── 消費的 SSOT ──────────────────────────────
+// - Field controls(Family 4,統一 size="sm"):Input / NumberInput / Select / Combobox /
+//   DatePicker + DatePickerRange(showTime)/ PeoplePicker — 按 ValueShape dispatch
+//   (ValueShape ↔ picker 對照 canonical:./data-table.spec.md「三、Operator × ValueShape SSOT」)
+// - className 直接 forward 給 inner Field control(不另開 wrapper div)—
+//   field-control-group.spec.md「forward className」canonical(2026-05-04 #2 fix)
+// - Operator / ValueShape SSOT:./filter-operators.ts(DATE_RELATIVE_OPTIONS / DATE_RELATIVE_GROUPS)
+// - Person pool:PeoplePicker PersonValue(對齊 cell-registry meta.people SSOT)
+// 設計規則:./filter-operators.spec.md「ValueShape canonical」+ ./data-table.spec.md「進階篩選」段
+
+import { Select, type SelectOption } from '@/design-system/components/Select/select'
+import { Combobox } from '@/design-system/components/Combobox/combobox'
+import { Input } from '@/design-system/components/Input/input'
+import { NumberInput } from '@/design-system/components/NumberInput/number-input'
+import { DatePicker, DatePickerRange } from '@/design-system/components/DatePicker/date-picker'
+import { PeoplePicker } from '@/design-system/components/PeoplePicker/people-picker'
+import type { PersonValue } from '@/design-system/components/PeoplePicker/person-display'
+import {
+  DATE_RELATIVE_OPTIONS,
+  DATE_RELATIVE_GROUPS,
+  type ValueShape,
+} from './filter-operators'
+
+// ── FilterValuePicker(value-picker switcher per ValueShape)────────────────
+//
+// 2026-05-03 M21 retract:本 helper 原獨立檔 filter-value-picker.tsx(187 行 / 1 consumer),
+// claim「未來 inline filter UI 共用」= premature abstraction → inline 回 panel。
+// 2026-07-14 拆檔 refactor:panel 822 行過 800 hard cap(file-size escalation)→ 重新抽出為
+// @internal 私有模組(非 public API 抽象,與 M21 不衝突;consumer 仍只見 DataTableFilterPanel)。
+
+export interface FilterValuePickerColInfo {
+  id: string
+  label: string
+  options?: Array<{ value: string; label: string }>
+  /** Person pool — person/multiPerson filter picker 用(2026-05-07 升級,SSOT 對齊 cell-registry) */
+  people?: Array<{ name: string; avatarUrl?: string; description?: string }>
+}
+
+export interface FilterValuePickerProps {
+  shape: ValueShape | null
+  value: unknown
+  onChange: (v: unknown) => void
+  colInfo?: FilterValuePickerColInfo
+  disabled?: boolean
+  /** 用 column.label 組「{label} 篩選值」(panel 每 row 不顯式 label,a11y 必填) */
+  ariaLabel?: string
+  /** Forward 給內部 Field control 的 className(2026-05-04 #2 fix)
+   *  避免外層包 wrapper div 破壞 FieldControlGroup CSS variants(rounded radii / margin overlap) */
+  className?: string
+}
+
+export function FilterValuePicker({
+  shape,
+  value,
+  onChange,
+  colInfo,
+  disabled,
+  ariaLabel,
+  className,
+}: FilterValuePickerProps) {
+  if (!shape || disabled) {
+    return <Input size="sm" value="" onChange={() => {}} placeholder="輸入值…" disabled aria-label={ariaLabel} className={className} />
+  }
+
+  switch (shape) {
+    case 'none':
+      return null
+
+    case 'text':
+      return (
+        <Input
+          size="sm"
+          value={String(value ?? '')}
+          onChange={(e) => onChange(e.target.value)}
+          placeholder="輸入值…"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'number':
+      return (
+        <NumberInput
+          size="sm"
+          value={typeof value === 'number' ? value : null}
+          onChange={(v) => onChange(v ?? '')}
+          placeholder="輸入數字…"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'date_single':
+      return (
+        <DatePicker
+          size="sm"
+          value={typeof value === 'string' ? value : null}
+          onChange={(v) => onChange(v ?? '')}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'date_range':
+      return (
+        <DatePickerRange
+          size="sm"
+          value={Array.isArray(value) && value.length === 2
+            ? (value as [string | null, string | null])
+            : null}
+          onChange={(v) => onChange(v)}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'date_relative': {
+      // 群組分類:Past / Current / Future(對齊 Linear / Notion idiom),走 Select.groups → SelectMenu
+      const opts: SelectOption[] = DATE_RELATIVE_OPTIONS.map((o) => ({
+        value: o.value,
+        label: o.label,
+        group: o.group,
+      }))
+      return (
+        <Select
+          size="sm"
+          options={opts}
+          groups={DATE_RELATIVE_GROUPS as unknown as Array<{ key: string; label: string }>}
+          value={String(value ?? '')}
+          onChange={(v) => onChange(v)}
+          placeholder="選擇相對日期"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+
+    case 'select_single': {
+      const opts: SelectOption[] = (colInfo?.options ?? []).map((o) => ({
+        value: o.value,
+        label: o.label,
+      }))
+      return (
+        <Select
+          size="sm"
+          options={opts}
+          value={String(value ?? '')}
+          onChange={(v) => onChange(v)}
+          placeholder="選擇值"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+
+    case 'select_multi': {
+      const opts = (colInfo?.options ?? []).map((o) => ({
+        value: o.value,
+        label: o.label,
+      }))
+      const arr = Array.isArray(value) ? (value as string[]) : []
+      return (
+        <Combobox
+          size="sm"
+          options={opts}
+          value={arr}
+          onChange={(v) => onChange(v)}
+          placeholder="選擇值…"
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+
+    case 'datetime_single':
+      return (
+        <DatePicker
+          size="sm"
+          showTime
+          value={typeof value === 'string' ? value : null}
+          onChange={(v) => onChange(v ?? '')}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    case 'datetime_range':
+      return (
+        <DatePickerRange
+          size="sm"
+          showTime
+          value={Array.isArray(value) && value.length === 2
+            ? (value as [string | null, string | null])
+            : null}
+          onChange={(v) => onChange(v)}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+
+    // person_single / person_multi — 走 PeoplePicker(2026-05-07 升級,對齊 cell-registry SSOT)。
+    // colInfo.people 來自 column meta.people。Filter value:
+    //   - person_single:存 PersonValue | null(picker emit array,我們取 [0])
+    //   - person_multi:存 PersonValue[]
+    case 'person_single': {
+      const v = value as PersonValue | null | undefined
+      return (
+        <PeoplePicker
+          size="sm"
+          value={v ?? null}
+          people={colInfo?.people ?? []}
+          onChange={(next) => onChange(next[0] ?? null)}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+    case 'person_multi': {
+      const v = Array.isArray(value) ? (value as PersonValue[]) : []
+      return (
+        <PeoplePicker
+          size="sm"
+          value={v}
+          people={colInfo?.people ?? []}
+          onChange={(next) => onChange(next)}
+          aria-label={ariaLabel}
+          className={className}
+        />
+      )
+    }
+    default:
+      return null
+  }
+}

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)
@@ -305,7 +305,7 @@ type FilterTreeNested = { mode: 'nested'; conjunction: 'and'|'or'; children: Fil
 
 ### 三、Operator × ValueShape SSOT
 
-`filter-operators.ts` 的 `OPERATOR_REGISTRY: Record<ColumnType, OperatorSpec[]>` 是唯一 truth。Panel 完全 data-driven:field 選 → load op set → 選 op → 由 `valueShape` dispatch picker(`filter-value-picker.tsx`)。`is_set` / `is_not_set` / `is_true` / `is_false`(`ValueShape='none'`)不渲 picker。
+`filter-operators.ts` 的 `OPERATOR_REGISTRY: Record<ColumnType, OperatorSpec[]>` 是唯一 truth。Panel 完全 data-driven:field 選 → load op set → 選 op → 由 `valueShape` dispatch picker(`data-table-filter-value-picker.tsx`,@internal;2026-07-14 file-size 拆檔自 panel)。`is_set` / `is_not_set` / `is_true` / `is_false`(`ValueShape='none'`)不渲 picker。
 
 ValueShape ↔ DS picker 對照(canonical 2026-05-02):
 
@@ -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`。