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

package/src/components/DataTable/cell-registry.tsx

@@ -4,7 +4,7 @@
 //
 // 對齊 M17 SSOT consolidation + audit recommendation:
 //   原 `renderTypedValue` switch + `EditableCellContent` switch 兩條平行 type-switch 已 collapse
-//   為**一張 type → cell component** registry。每個 cell component 同時處理 display / edit mode,
+//   為**一張 type → cell component** registry。每個 cell component 同時處理 view / edit mode,
 //   靠底層 Field control 的 `mode` prop 切換。
 //
 // 設計原則:
@@ -19,7 +19,7 @@
 import * as React from 'react'
 import type { ComponentType } from 'react'
 import { Pencil } from 'lucide-react'
-import { cn } from '@/lib/utils'
+import { cn, lineClampClass } from '@/lib/utils'
 import type { ColumnType } from './column-types'
 import { Input as InputPublic } from '@/design-system/components/Input/input'
 import { Textarea as TextareaPublic } from '@/design-system/components/Textarea/textarea'
@@ -55,7 +55,7 @@ const Checkbox = CheckboxPublic as WithFieldVariantInternal<typeof CheckboxPubli
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
-export type CellMode = 'display' | 'edit'
+export type CellMode = 'view' | 'edit'
 export type CellSize = 'sm' | 'md' | 'lg'
 
 export interface CellComponentProps {
@@ -65,13 +65,13 @@ export interface CellComponentProps {
   meta: Record<string, any>
   mode: CellMode
   size: CellSize
+  /** 該 cell 的 accessible name(= 欄標題)。naked Field 控件在 cell 內無 FieldLabel,
+   *  漏此名 → editor 成無名控件(axe aria-input-field-name / select-name)。由 renderCellContent
+   *  從 columnDef.header 解析後注入。對齊 AG Grid / MUI X「editor aria-label = column headerName」。 */
+  ariaLabel?: string
   autoRowHeight: boolean
   /** 該 cell 是否可編。replaces 舊 `meta._editable` 私有 flag(Phase C M1 hack 移除)。 */
   isEditable?: boolean
-  /** 2026-05-13:cell 是否 disabled(state overlay,orthogonal to display/edit lifecycle)。
-   *  per codex Q3 verdict:不擴 CellMode='disabled',加 prop。各 Cell function 收 true 時
-   *  傳 `mode='disabled'` 給 inner Field control,各 Field 內部走具體 disabled token(非 wrapper opacity)。 */
-  isDisabled?: boolean
   /** Cell 進 edit mode → 提交新值(blur / Enter / option select 都觸發)— 提交後**自動 exit edit**。
    *  適用 single-shot commit:string / number / select(single)/ person(single)/ date / time / boolean / url。 */
   onCommit?: (next: unknown) => void
@@ -112,44 +112,41 @@ function makeKeyHandler(
 
 const sizeForInput = (size: CellSize): CellSize => size
 
-/** 2026-05-13 Q3 helper(per codex Q3 verdict):cell display + isDisabled → Field mode='disabled'。
- *  Cell display lifecycle 不擴 CellMode='disabled',而是各 Cell 在 display branch 翻譯 isDisabled
- *  → Field mode='disabled' prop。inner Field 內部走具體 disabled token(text-fg-disabled / bg-disabled 等),
- *  非 wrapper blanket opacity-disabled 逃生艙(per color.spec.md:729)。 */
-const displayOrDisabled = (isDisabled?: boolean): 'display' | 'disabled' =>
-  isDisabled ? 'disabled' : 'display'
+// 2026-07-16 round16:cell「disabled」態廢除(世界級 grid 無 disabled cell — MUI X / AG Grid /
+//   Handsontable 皆只有 editable/readonly;meta.disabled 全庫 0 消費)。cell view 態一律 mode="view",
+//   鎖定用 `editable:(row)=>false` 閘(= isCellEditable 模型)。原 displayOrDisabled helper 已移除。
 
 // ── Cell Components ──────────────────────────────────────────────────────────
 
-function StringCell({ value, meta, mode, size, isDisabled, autoRowHeight, onCommit, onCancel, onDraft }: CellComponentProps) {
+function StringCell({ value, meta, mode, size, autoRowHeight, onCommit, onCancel, onDraft, ariaLabel }: CellComponentProps) {
   // 2026-05-14 I9 fix(per codex+Layer A 共識):meta.maxLines opt-in line-clamp。
-  // display autoRow 用 Tailwind arbitrary line-clamp 支援 N rows;edit textarea field-sizing
+  // view autoRow 用 Tailwind arbitrary line-clamp 支援 N rows;edit textarea field-sizing
   // 已 auto-grow to content,natural match clamp。
   // 2026-05-16 Round 5 audit Dim 27 fix:narrow type 取代 `as any` cast。
   const maxLines: number | undefined = (meta as { maxLines?: number } | undefined)?.maxLines
-  const clampClass = maxLines && autoRowHeight ? `line-clamp-[${maxLines}]` : undefined
+  const clampClass = autoRowHeight ? lineClampClass(maxLines) : undefined
   // string type canonical(2026-05-05 v2 user 校正:input space ≥ display space):
-  //   - autoRowHeight: Textarea(display + edit)— display wrap text 撐高 row,edit textarea
+  //   - autoRowHeight: Textarea(view + edit)— view wrap text 撐高 row,edit textarea
   //     多行輸入、`!h-full` 填 cell。對齊 Notion long-text cell canonical。
-  //   - fixed: Input(display + edit)— 單行 truncate display,單行 input edit;Field naked intrinsic
-  //     高 = cell 高 = h-field-md,文字位置 display↔edit 完全一致。對齊 AG Grid / Material X-Grid。
+  //   - fixed: Input(view + edit)— 單行 truncate view,單行 input edit;Field naked intrinsic
+  //     高 = cell 高 = h-field-md,文字位置 view↔edit 完全一致。對齊 AG Grid / Material X-Grid。
   //   - autoRowHeight 是 table 框架決定(consumer 不需 per-column 設 meta.wrap)。
   //   - 互動(Textarea):Esc cancel / Cmd|Ctrl+Enter commit / blur commit;Enter 保留換行
   //   - 互動(Input):Esc cancel / Enter commit / blur commit
   const v = value != null ? String(value) : ''
-  if (mode === 'display') {
+  if (mode === 'view') {
     // size 必傳:DataTable cell 字級隨 size 變(sm/md text-body / lg text-body-lg),
     // 對齊 Field family size→font SSOT(field-wrapper.tsx:60-64)。漏傳 → fallback md → lg 表格
     // 字卡 14px 跟 Select/Date 等有傳 size 的 cell 不一致(2026-06-08 user 抓 frozen string 欄字偏小)。
     return autoRowHeight
-      ? <Textarea variant="naked" mode={displayOrDisabled(isDisabled)} value={v} size={size} className={clampClass} />
-      : <Input variant="naked" mode={displayOrDisabled(isDisabled)} value={v} size={size} />
+      ? <Textarea variant="naked" mode="view" value={v} size={size} className={clampClass} aria-label={ariaLabel} />
+      : <Input variant="naked" mode="view" value={v} size={size} aria-label={ariaLabel} />
   }
   if (autoRowHeight) {
     // 2026-05-14 I8 fix(per codex verdict + user 抓「edit cell shrink」):
     // 原 `wrapRows = value.length / 40` 字元估算不準(對應實際 column width 不同
     // → cell 進 edit shrink)。改 CSS `field-sizing: content`(Chrome 123+ / FF 122+ /
-    // Safari 17+)讓 textarea 自動 grow to content,匹配 display wrap 真實高度。
+    // Safari 17+)讓 textarea 自動 grow to content,匹配 view wrap 真實高度。
     // Fallback rows 仍保留給舊 browser(rows attr 在 field-sizing 支援時被覆蓋)。
     const newlineRows = (v.match(/\n/g) || []).length + 1
     const wrapRows = Math.ceil(v.length / 40)
@@ -158,6 +155,7 @@ function StringCell({ value, meta, mode, size, isDisabled, autoRowHeight, onComm
       <Textarea
         autoFocus
         variant="naked"
+        aria-label={ariaLabel}
         size={sizeForInput(size)}
         rows={estimateRows}
         defaultValue={v}
@@ -180,6 +178,7 @@ function StringCell({ value, meta, mode, size, isDisabled, autoRowHeight, onComm
     <Input
       autoFocus
       variant="naked"
+      aria-label={ariaLabel}
       size={sizeForInput(size)}
       defaultValue={v}
       onChange={(e) => onDraft?.(e.target.value)}
@@ -189,20 +188,21 @@ function StringCell({ value, meta, mode, size, isDisabled, autoRowHeight, onComm
   )
 }
 
-function NumberCell({ value, meta, mode, size, isDisabled, onCommit, onCancel, onDraft }: CellComponentProps) {
+function NumberCell({ value, meta, mode, size, onCommit, onCancel, onDraft, ariaLabel }: CellComponentProps) {
   // currency 透過 columnType-aware prefix:type='currency' → 預設 '$'(可 override)
   const isCurrency = meta?.type === 'currency'
   const prefix = isCurrency ? (meta?.prefix ?? '$') : meta?.prefix
-  // React #310 fix:useState 必在 display early-return 前無條件呼叫。同一 memo'd cell instance
-  // 在 display↔edit 切換時被重用(render site 無 key={mode},data-table.tsx:1352),hook 數量不可變,
+  // React #310 fix:useState 必在 view early-return 前無條件呼叫。同一 memo'd cell instance
+  // 在 view↔edit 切換時被重用(render site 無 key={mode},data-table.tsx:1352),hook 數量不可變,
   // 否則 Rules of Hooks violation → React #310 crash。對齊 combobox/select hoist pattern。
   const initial = typeof value === 'number' ? value : null
   const [localValue, setLocalValue] = React.useState<number | null>(initial)
-  if (mode === 'display') {
+  if (mode === 'view') {
     return (
       <NumberInput
         variant="naked"
-        mode={displayOrDisabled(isDisabled)}
+        mode="view"
+        aria-label={ariaLabel}
         value={value as number | null}
         // size 必傳(同 StringCell)— currency/number cell 字級隨 DataTable size 變,對齊 Field SSOT。
         size={size}
@@ -215,13 +215,14 @@ function NumberCell({ value, meta, mode, size, isDisabled, onCommit, onCancel, o
   }
   // Edit mode value pre-fill canonical(2026-05-05):NumberInput edit 強制 controlled
   // (`value={value ?? ''}`)— 若 NumberCell 以 `defaultValue` 傳入,NumberInput value=undefined → ''
-  // empty。對齊 cell-as-input「edit mode 自動帶入 display 值」(對齊 Notion / Airtable 共識),
+  // empty。對齊 cell-as-input「edit mode 自動帶入 view 值」(對齊 Notion / Airtable 共識),
   // 改用 local state controlled。User typing → setLocalValue;blur/Enter → onCommit(localValue)。
-  // (initial + useState 已 hoist 到 display-return 前 — 見上方 React #310 fix。)
+  // (initial + useState 已 hoist 到 view-return 前 — 見上方 React #310 fix。)
   return (
     <NumberInput
       autoFocus
       variant="naked"
+      aria-label={ariaLabel}
       size={sizeForInput(size)}
       value={localValue}
       onChange={(v) => { setLocalValue(v); onDraft?.(v) }}
@@ -244,25 +245,25 @@ function NumberCell({ value, meta, mode, size, isDisabled, onCommit, onCancel, o
 // (對齊 Airtable / Notion canonical:click 外即關)。
 const dismissOnClose = (onCancel?: () => void) => (open: boolean) => { if (!open) onCancel?.() }
 
-// Mode-keyed remount canonical(2026-05-05):display↔edit 切換時,因 React reconciliation 同 type 同
-// position 會重用 instance,導致 `useState(defaultOpen)` 只在首次 mount 跑(那時 mode='display'
+// Mode-keyed remount canonical(2026-05-05):view↔edit 切換時,因 React reconciliation 同 type 同
+// position 會重用 instance,導致 `useState(defaultOpen)` 只在首次 mount 跑(那時 mode='view'
 // defaultOpen 沒給→預設 false)。後續 mode='edit' 即使傳 defaultOpen=true 也無效。
 // Fix:`key={mode}` 強制 React unmount + remount,每次切 mode 都重跑 useState init。
-// 對齊 Notion / Airtable cell-as-input「display 跟 edit 是不同 mount cycle」語義。
+// 對齊 Notion / Airtable cell-as-input「view 跟 edit 是不同 mount cycle」語義。
 
-function DateCell({ value, meta, mode, size, isDisabled, onCommit, onCancel }: CellComponentProps) {
-  if (mode === 'display') {
+function DateCell({ value, meta, mode, size, onCommit, onCancel }: CellComponentProps) {
+  if (mode === 'view') {
     return (
       <DatePicker
-        key="display"
+        key="view"
         variant="naked"
-        mode={displayOrDisabled(isDisabled)}
+        mode="view"
         value={value as string | null}
         size={size}
         formatOptions={meta?.formatOptions}
         locale={meta?.locale}
         // 2026-07-08 user 拍板 A 案(推翻 2026-05-10/06-26 兩次拍板,per 6 家 benchmark 6/6 共識
-        // Ant/MUI X/AG Grid/Atlaskit/Notion/Airtable:display 態零恆顯型別 icon;editable
+        // Ant/MUI X/AG Grid/Atlaskit/Notion/Airtable:view 態零恆顯型別 icon;editable
         // affordance 統一 = hover outline(field.spec.md L4)。showDisplayEndIcon 不再傳
         //(prop 保留為 spreadsheet-flavored 消費端 opt-in 逃生門,見 field.spec.md L6)。
       />
@@ -283,18 +284,18 @@ function DateCell({ value, meta, mode, size, isDisabled, onCommit, onCancel }: C
   )
 }
 
-function TimeCell({ value, meta, mode, size, isDisabled, onCommit, onCancel }: CellComponentProps) {
-  if (mode === 'display') {
+function TimeCell({ value, meta, mode, size, onCommit, onCancel }: CellComponentProps) {
+  if (mode === 'view') {
     return (
       <TimePicker
-        key="display"
+        key="view"
         variant="naked"
-        mode={displayOrDisabled(isDisabled)}
+        mode="view"
         value={value as string | null}
         size={size}
         formatOptions={meta?.formatOptions}
         locale={meta?.locale}
-        // showDisplayEndIcon 不傳 — 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
+        // showDisplayEndIcon 不傳 — 2026-07-08 A 案:view 態零恆顯 icon(同 DateCell 註)
       />
     )
   }
@@ -314,22 +315,22 @@ function TimeCell({ value, meta, mode, size, isDisabled, onCommit, onCancel }: C
   )
 }
 
-function SelectCell({ value, meta, mode, size, isDisabled, onCommit, onCancel }: CellComponentProps) {
-  // Display canonical(2026-05-05):cell IS variant,default plain text(no Tag pill 疊在 cell border 內)。
+function SelectCell({ value, meta, mode, size, onCommit, onCancel }: CellComponentProps) {
+  // View canonical(2026-05-05):cell IS variant,default plain text(no Tag pill 疊在 cell border 內)。
   // Consumer 可在 column meta.display='tag' opt-in 內容導向的 Tag 視覺(category 含色彩標籤等)。
   // 對齊 JTable / AG Grid「renderer/editor 視覺一致」canonical。
   const displayMode = (meta?.display as 'plain' | 'tag' | undefined) ?? 'plain'
-  if (mode === 'display') {
+  if (mode === 'view') {
     return (
       <Select
-        key="display"
+        key="view"
         variant="naked"
-        mode={displayOrDisabled(isDisabled)}
+        mode="view"
         value={value as string | null}
         options={meta?.options ?? []}
         size={size}
         display={displayMode}
-        // showDisplayEndIcon 不傳 — 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
+        // showDisplayEndIcon 不傳 — 2026-07-08 A 案:view 態零恆顯 icon(同 DateCell 註)
         selectedItemRenderer={meta?.selectedItemRenderer}  // 2026-07-08 WM 戰役:status 類彩色 cell 顯示通道
       />
     )
@@ -354,19 +355,19 @@ function SelectCell({ value, meta, mode, size, isDisabled, onCommit, onCancel }:
   )
 }
 
-function MultiSelectCell({ value, meta, mode, size, isDisabled, autoRowHeight, onCommitLive, onCancel }: CellComponentProps) {
+function MultiSelectCell({ value, meta, mode, size, autoRowHeight, onCommitLive, onCancel }: CellComponentProps) {
   const wrap = autoRowHeight && meta?.wrap === true
-  if (mode === 'display') {
+  if (mode === 'view') {
     return (
       <Combobox
-        key="display"
+        key="view"
         variant="naked"
-        mode={displayOrDisabled(isDisabled)}
+        mode="view"
         value={(value as string[] | null) ?? []}
         options={meta?.options ?? []}
         wrap={wrap}
         size={size}
-        // showDisplayEndIcon 不傳 — 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
+        // showDisplayEndIcon 不傳 — 2026-07-08 A 案:view 態零恆顯 icon(同 DateCell 註)
       />
     )
   }
@@ -386,10 +387,10 @@ function MultiSelectCell({ value, meta, mode, size, isDisabled, autoRowHeight, o
   )
 }
 
-function PersonCell({ value, mode, size, isDisabled, onCommit, onCancel, meta }: CellComponentProps) {
-  if (mode === 'display') {
-    // 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
-    return <PeoplePicker key="display" variant="naked" mode={displayOrDisabled(isDisabled)} value={value as PersonValue | null} size={size} />
+function PersonCell({ value, mode, size, onCommit, onCancel, meta }: CellComponentProps) {
+  if (mode === 'view') {
+    // 2026-07-08 A 案:view 態零恆顯 icon(同 DateCell 註)
+    return <PeoplePicker key="view" variant="naked" mode="view" value={value as PersonValue | null} size={size} />
   }
   return (
     <PeoplePicker
@@ -406,10 +407,10 @@ function PersonCell({ value, mode, size, isDisabled, onCommit, onCancel, meta }:
   )
 }
 
-function MultiPersonCell({ value, mode, size, isDisabled, onCommitLive, onCancel, meta }: CellComponentProps) {
-  if (mode === 'display') {
-    // 2026-07-08 A 案:display 態零恆顯 icon(同 DateCell 註)
-    return <PeoplePicker key="display" variant="naked" mode={displayOrDisabled(isDisabled)} value={(value as PersonValue[]) ?? []} size={size} />
+function MultiPersonCell({ value, mode, size, onCommitLive, onCancel, meta }: CellComponentProps) {
+  if (mode === 'view') {
+    // 2026-07-08 A 案:view 態零恆顯 icon(同 DateCell 註)
+    return <PeoplePicker key="view" variant="naked" mode="view" value={(value as PersonValue[]) ?? []} size={size} />
   }
   // Multi 用 onCommitLive(commit 但不 exit edit)— 每勾一人即時生效,popover 持續開
   // 直到點外面;onOpenChange(false) → onCancel exit edit。對齊 multiSelect canonical。
@@ -427,14 +428,12 @@ function MultiPersonCell({ value, mode, size, isDisabled, onCommitLive, onCancel
   )
 }
 
-function BooleanCell({ value, mode, meta, size, isEditable, isDisabled, onCommit }: CellComponentProps) {
-  // boolean 不分 read/edit mode — display 渲 mode='display' 純展示;editable 時直接 toggle Checkbox
-  // 2026-05-13 codex V1 fix:editable=true + disabled=true 之前 fall through to live Checkbox,
-  // onCheckedChange 仍 fire(violate disabled contract)。Fix:`!isEditable || isDisabled` →
-  // 走 display branch,Checkbox 拿 disabled mode + 不接 onCheckedChange。
-  if (mode === 'display' && (!isEditable || isDisabled)) {
+function BooleanCell({ value, mode, meta, size, isEditable, onCommit }: CellComponentProps) {
+  // boolean 不分 read/edit mode — view 渲 mode='view' 純展示;editable 時直接 toggle Checkbox。
+  // 不可編(!isEditable)→ 走 view branch,Checkbox mode="view" 純展示不接 onCheckedChange。
+  if (mode === 'view' && !isEditable) {
     // size 傳入 → boolean 值 icon(Check/X)@lg 縮放對齊其他 cell(對齊 editable 分支同 size 邏輯)
-    return <Checkbox variant="naked" size={size === 'lg' ? 'lg' : 'md'} mode={displayOrDisabled(isDisabled)} checked={value === true} />
+    return <Checkbox variant="naked" size={size === 'lg' ? 'lg' : 'md'} mode="view" checked={value === true} />
   }
   return (
     <Checkbox
@@ -448,21 +447,21 @@ function BooleanCell({ value, mode, meta, size, isEditable, isDisabled, onCommit
 
 /**
  * UrlCell(2026-07-14 docblock 對齊實作):
- *   display branch = `<LinkInput mode={displayOrDisabled(isDisabled)}>`(URL parse / hostname
+ *   view branch = `<LinkInput mode="view">`(URL parse / hostname
  *   顯示一致性 SSOT);editable 互動:hover 時右側出 Pencil 鈕 → 進 edit(保留 link click 語意)。
  *   edit branch = plain `<Input variant="naked">`(LinkInput edit 的 controlled value 衝突
  *   revert,詳下方 edit branch 註解);URL 驗證 deferred 到 onCommit(consumer 端 validate)。
  */
-function UrlCell({ value, meta, mode, size, isDisabled, isEditable, onRequestEdit, onCommit, onCancel }: CellComponentProps) {
-  if (mode === 'display') {
+function UrlCell({ value, meta, mode, size, isEditable, onRequestEdit, onCommit, onCancel }: CellComponentProps) {
+  if (mode === 'view') {
     // showDisplayEndIcon ← D path Phase 2(2026-05-08):Field naked wrapper 包 anchor,與 Input edit 同 chrome。
     // LinkInput 此 prop = wrapper-only(無 icon,field.spec.md L6 例外)→ A 案(2026-07-08)不撤;
     // 但修 I1:原無條件 true 違反「= isEditable」knob 等式(field-controls.spec.md cell 例外),改等式。
     const display = (
-      <LinkInput variant="naked" mode={displayOrDisabled(isDisabled)} value={value as string | null} label={meta?.linkLabel} size={size} showDisplayEndIcon={isEditable === true} />
+      <LinkInput variant="naked" mode="view" value={value as string | null} label={meta?.linkLabel} size={size} showDisplayEndIcon={isEditable === true} />
     )
-    // 2026-05-13 codex V1 fix:disabled URL 不顯 Pencil affordance(parent onRequestEdit 已被攔但 UI 仍誤導)
-    if (!isEditable || isDisabled) return display
+    // 不可編 URL 不顯 Pencil affordance(純 view 顯示連結,無編輯入口)
+    if (!isEditable) return display
     // editable read mode:hover Pencil 鈕(對齊 spec 第十二段「url:read = 連結 + Pencil」)
     return (
       <span className="group/cell relative flex items-center w-full"> {/* @naked-row-mode-allow: URL hover-Pencil 是 inline action 不是 value content,items-center 鎖 Pencil 對齊行高第一行(autoRow 跟 fixed 皆同視覺正確) */}
@@ -540,7 +539,7 @@ function buildCellWithSurface(Inner: ComponentType<CellComponentProps>, key: str
             漏傳 size 的 cell 也自動繼承(根治「新 cell 漏傳 size」class);size primitive 不破壞 memo identity。*/}
         <FieldSurfaceSizeProvider size={props.size}>
           {/* 2026-07-08 user 拍板:cell 可編輯訊號經獨立 boolean context 注給 child Field controls,
-              讓 useFieldEmptyDisplay 分流「可編輯 cell 空 display → 空白」vs「不可編輯 cell → '-'」。
+              讓 useFieldEmptyDisplay 分流「可編輯 cell 空 view → 空白」vs「不可編輯 cell → '-'」。
               boolean primitive 不破壞 memo identity(同 size context)。 */}
           <FieldSurfaceEditableProvider isEditable={props.isEditable ?? false}>
             <Inner {...props} />

package/src/components/DataTable/column-types.ts

@@ -65,7 +65,7 @@ declare module '@tanstack/react-table' {
     wrap?: boolean
     /**
      * Max visible lines before ellipsis(2026-05-14 I9 per codex verdict + user 拍板)。
-     * Only effective when `autoRowHeight + wrap=true`。Display 用 `line-clamp-N`,edit textarea
+     * Only effective when `autoRowHeight + wrap=true`。view 用 `line-clamp-N`,edit textarea
      * 高度 match clamp。對齊 Notion 「Truncate」row toggle / AG Grid `cellClassRules` 上限 row height。
      * Default = undefined(無 clamp,完整 wrap)。
      */
@@ -162,22 +162,9 @@ declare module '@tanstack/react-table' {
      * Esc cancel / blur or Enter commit。Commit 觸發 `onCellCommit`。
      */
     editable?: boolean | ((row: TData) => boolean)
-    /**
-     * Inline disabled state(2026-05-13 Stream C Cluster B Q3 ship,per codex Q3 verdict):
-     * cell 不可操作 state(orthogonal to editable readonly)。
-     * - `true`:cell 永遠 disabled
-     * - `false` / undef(default):cell normal
-     * - `(row) => boolean`:per-row 動態(e.g. row.archived 或 row.locked 才 disabled)
-     *
-     * 視覺(per `color.spec.md` `--bg-disabled` component-state token):
-     * - TD 外殼:`bg-disabled` + `cursor-not-allowed` + 抑制 hover ring
-     * - Cell content(Field family):`mode='disabled'` → 各 Field type 內部走具體 disabled token
-     * - edit entry 抑制:disabled cell 點擊不進 edit(對齊 `editable && !disabled` invariant)
-     *
-     * 跟 `editable=false` 區分:editable=false = readonly(可看不可編);disabled = 不可操作 state。
-     * 對齊 MUI X `isCellEditable` + cellClassName / AG Grid `cellClassRules` / Notion locked properties。
-     */
-    disabled?: boolean | ((row: TData) => boolean)
+    // 2026-07-16 round16:cell `disabled` 已廢除。世界級 grid(MUI X isCellEditable / AG Grid editable /
+    //   Handsontable readOnly)皆無 disabled cell 態 — 鎖定用 `editable:(row)=>false`(可看不可編、不灰化),
+    //   非 disabled 灰化態。原 `disabled?: boolean | ((row)=>boolean)` + bg-disabled TD 灰化全移除(全庫 0 消費)。
     /**
      * Locked column — column reorder 不可拖,Notion 「primary column」 pattern。
      * 對齊 SKU / ID 等不可移欄位。

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

@@ -27,8 +27,7 @@ import { Eye, EyeOff, Lock, GripVertical, Search, RotateCcw, X as XIcon } from '
 import { Button } from '@/design-system/components/Button/button'
 import { ButtonDivider } from '@/design-system/components/Button/button-group'
 import { Input } from '@/design-system/components/Input/input'
-import { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'
-import { PopoverHeader, PopoverFooter, PopoverTitle, PopoverClose } from '@/design-system/components/Popover/popover'
+import { PopoverHeader, PopoverBody, PopoverFooter, PopoverTitle, PopoverClose } from '@/design-system/components/Popover/popover'
 import { ItemPrefix, ItemLabel, ItemInlineActionButton, ROW_PADDING_BY_SIZE } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { cn } from '@/lib/utils'
 import { DndContext, closestCenter, type DragEndEvent } from '@dnd-kit/core'
@@ -130,8 +129,19 @@ export function DataTableColumnVisibilityPanel({
     onColumnOrderChange!(next)
   }
 
+  // 2026-07-18 決策16 錯誤史(明記以免再犯):原本這個 panel 是 Fragment + fixed `ScrollArea max-h-72`,
+  //   與 sibling FilterPanel/SortManager(root-div + viewport-aware SurfaceBody)不一致。我給過**兩個都錯**
+  //   的辯護理由 —— (1)「PopoverHeader 用 -mx 負邊距、包 root 會破壞」= 錯(SurfaceHeader 用正 px-loose+border-b,
+  //   無 -mx);(2)「sibling 自刻 header 不用 primitive」= 錯(三 panel 皆消費 SurfaceHeader/PopoverHeader primitive)。
+  //   真正差異只是 body/scroll 策略。multi-agent SSOT consistency 稽核定案:**是 drift,該統一**(fixed 288px cap
+  //   在高螢幕多欄下劣於 sibling 的 viewport-adaptive;且是唯一不能當 template 複製的 panel)。故下方已改成 canonical shape。
   return (
-    <>
+    // 決策16 定案(2026-07-18,SSOT consistency 稽核後):對齊 sibling FilterPanel/SortManager 的
+    //   overlay-surface canonical shape —— root `<div flex flex-col h-full min-h-0>`(M25 viewport-aware
+    //   scroll chain)+ viewport-adaptive `PopoverBody`(取代原 fixed `ScrollArea max-h-72`)。三個
+    //   DataTable state-panel 收斂成同一形狀,body 隨視窗高度自適應(高螢幕多欄不再硬卡 288px)。
+    //   寬度仍由 consumer 的 `<PopoverContent w-72>` 提供(panel root w-full 撐滿)。
+    <div className="flex flex-col h-full min-h-0 w-full">
       <PopoverHeader hideClose>
         <div className="flex items-center gap-1 w-full min-w-0">
           <PopoverTitle className="flex-1">欄位顯示</PopoverTitle>
@@ -151,17 +161,20 @@ export function DataTableColumnVisibilityPanel({
         </div>
       </PopoverHeader>
       {searchable && (
-        <div className="px-[var(--layout-space-loose)] pt-[var(--layout-space-tight)]">
+        <div className="shrink-0 px-[var(--layout-space-loose)] pt-[var(--layout-space-tight)]">
           <Input
             size="md"
             placeholder="搜尋欄位…"
+            aria-label="搜尋欄位"
             value={search}
             onChange={(e) => setSearch(e.target.value)}
             startIcon={Search}
           />
         </div>
       )}
-      <ScrollArea className="max-h-72">
+      {/* viewport-adaptive body(List-as-region idiom:PopoverBody !px-0 !py-0 撤 chrome padding,
+          內層 py-2 給垂直呼吸、row 自帶 px-loose 水平 padding)。取代原 fixed ScrollArea max-h-72。 */}
+      <PopoverBody className="!px-0 !py-0">
         <div className="py-2 flex flex-col" style={{ '--item-prefix-slot': '16px' } as React.CSSProperties}>
           {dndEnabled ? (
             <DndContext collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
@@ -196,13 +209,13 @@ export function DataTableColumnVisibilityPanel({
             ))
           )}
         </div>
-      </ScrollArea>
+      </PopoverBody>
       <PopoverFooter className="justify-start">
         <Button variant="tertiary" size="sm" onClick={handleBulkToggle}>
           {allVisible ? '全部隱藏' : '顯示全部'}
         </Button>
       </PopoverFooter>
-    </>
+    </div>
   )
 }
 

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

@@ -126,8 +126,9 @@ const newEmptyGroup = (): FilterGroup => ({
 // ── Component Props ─────────────────────────────────────────────────────
 
 export interface DataTableFilterPanelProps<TData> {
-  /** flat(無 group)or nested(1-level group)— consumer 拍板 */
-  mode: 'flat' | 'nested'
+  // 2026-07-18 決策17:移除獨立 `mode` prop(單一真相源 = `value.mode` discriminant)——
+  //   舊設計 mode + value.mode 兩來源型別允許矛盾(mode='nested' 配 flat value → CTA 錯文案 + 死操作);
+  //   無外部消費者傳 mode(grep 0),全由 value.mode 推導。對齊 MUI X GridFilterModel / AG Grid 單一 model。
   /** 可被 filter 的 columns */
   columns: ColumnDef<TData, any>[]
   /** 當前 FilterTree(controlled) */
@@ -151,7 +152,6 @@ export interface DataTableFilterPanelProps<TData> {
 
 // 內部 fn — generic + ref 轉發。export 走 cast(對齊 DataTable 同 pattern)
 function DataTableFilterPanelInner<TData>({
-  mode,
   columns,
   value,
   onChange,
@@ -314,7 +314,7 @@ function DataTableFilterPanelInner<TData>({
     // 必加 `min-h-0` 才能讓 panel 在 PopoverContent max-h cap 下正確 shrink + body scroll。
     <div ref={ref} className={cn(
       'flex flex-col h-full min-h-0',
-      mode === 'nested'
+      value.mode === 'nested'
         ? 'w-[min(760px,calc(100vw-2rem))]'
         : 'w-[min(640px,calc(100vw-2rem))]',
       className,
@@ -387,9 +387,9 @@ function DataTableFilterPanelInner<TData>({
         <div>
           <Button
             variant="tertiary" size="sm" startIcon={Plus}
-            onClick={mode === 'flat' ? addFlatCondition : addGroup}
+            onClick={value.mode === 'flat' ? addFlatCondition : addGroup}
           >
-            {mode === 'nested' ? '加入篩選器' : '加篩選'}
+            {value.mode === 'nested' ? '加入篩選器' : '加篩選'}
           </Button>
         </div>
       </SurfaceBody>

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

@@ -63,8 +63,8 @@ interface DataTableInteractionLayerProps {
    * truthy → layer call this 拿 React node(已 bind value/onCommit/onCancel from controller),
    * 在 ActiveEditorHost portal(z 3,float rect)render 之。
    *
-   * Per codex Q6.2 outline:cell 永遠 mode="display"(SSOT preserved);portal host 渲
-   * mode="edit" 同 registry component;float pass-through + z-index 3 cover display below。
+   * Per codex Q6.2 outline:cell 永遠 mode="view"(SSOT preserved);portal host 渲
+   * mode="edit" 同 registry component;float pass-through + z-index 3 cover view below。
    */
   activeEditorRender?: (cellId: CellId, rect: CellRect) => React.ReactNode
 }
@@ -441,7 +441,7 @@ function ClipMask({ clipRect, children }: { clipRect: CellRect; children: React.
  *
  * Per codex Q2 verdict:不該進 CellRingOverlay primitive — 它是 host 不是 ring。
  *   - pointerEvents:auto(child Field 接收 click / keyboard)
- *   - background:var(--canvas)(opaque cover display Field below;Cell SSOT 保留)
+ *   - background:var(--canvas)(opaque cover view Field below;Cell SSOT 保留)
  *   - z-index 3(above hover / selected / range)
  *   - children = activeEditorRender 的回傳 React node
  *

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

@@ -197,11 +197,11 @@ function SortRow({
         {...listeners}
       />
       <div className="flex-1 min-w-0">
-        <Select size="sm" options={optionsForRow} value={sort.id} onChange={onChangeId} />
+        <Select size="sm" aria-label="排序欄位" options={optionsForRow} value={sort.id} onChange={onChangeId} />
       </div>
       <div className="w-32 shrink-0">
         {/* minRows={2} — 升冪/降冪只 2 選項,顯式縮 menu 高度(Q5) */}
-        <Select size="sm" options={DIRECTION_OPTIONS} value={sort.desc ? 'desc' : 'asc'} onChange={onChangeDir} minRows={2} />
+        <Select size="sm" aria-label="排序方向" options={DIRECTION_OPTIONS} value={sort.desc ? 'desc' : 'asc'} onChange={onChangeDir} minRows={2} />
       </div>
       {/* Trash 用 text Button(Q4 對齊 filter panel)— form-control row 必 Field 同高 */}
       <Button variant="text" size="sm" iconOnly startIcon={Trash2} aria-label="刪除" onClick={onRemove} />