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

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

@@ -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} />

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

@@ -1,9 +1,10 @@
 // @anatomy-rationale:
-//   SizeMatrix represented as RowHeightMatrix per row-density semantics —
-//     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)。
+//   SizeMatrix 以 RowHeightMatrix 呈現 —— DataTable 的 size(sm / md / lg)主要
+//     體現在 row height 這個結構決策上(spec.md「Size 不等於 density」:size 是
+//     這張表格「需要多緊湊」的結構決策,density 是全域使用者偏好,兩者不同軸,
+//     不套用 compact / cozy / comfortable 等外部密度命名)。lg 同時連動字級放大
+//     (sm/md → text-body / lg → text-body-lg,對齊 Field,SSOT fieldDisplayTextClass)。
+//     @benchmark-unverified: Linear / Notion / Airtable 的 row-density 控件僅為外部近似參照,非 DS 命名依據。
 //   StateBehavior covered by ColorMatrix「Row 狀態色彩」段(default / hover /
 //     selected / disabled)+ Features「排序」段。Row 互動是 row-level
 //     而非元件 level,集中於 Row 色彩展示更直觀。
@@ -71,7 +72,7 @@ export const Overview: Story = {
       <div className="flex flex-col gap-10">
         <div>
           <H3>Anatomy</H3>
-          <Desc>DataTable 基於 TanStack Table,透過 `meta.type` column type 系統自動套用對應 Field Control 的 Display 子元件渲染 cell。底層用 `&lt;div&gt;` + ARIA role(不用語義 `&lt;table&gt;`)——虛擬捲動需要絕對定位 row,frozen column 需要獨立 scroll 區域,table 的佈局模型兩者都不支援。</Desc>
+          <Desc>DataTable 基於 TanStack Table,透過 `meta.type` column type 系統自動套用對應 Field Control 的 view 態渲染 cell。底層用 `&lt;div&gt;` + ARIA role(不用語義 `&lt;table&gt;`)——虛擬捲動需要絕對定位 row,frozen column 需要獨立 scroll 區域,table 的佈局模型兩者都不支援。</Desc>
           <DataTable columns={columns} data={SAMPLE_DATA} height="auto" />
         </div>
 
@@ -83,7 +84,7 @@ export const Overview: Story = {
               <tbody>
                 <tr><Td>L1 Structure</Td><Td>DOM 結構 + 捲動行為</Td><Td mono>&lt;div&gt; + ARIA role="table/row/cell" + useVirtualizer</Td></tr>
                 <tr><Td>L2 Typography / Spacing</Td><Td>Row 高度 / Cell padding / 對齊</Td><Td mono>--table-row-* + --field-height-* token</Td></tr>
-                <tr><Td>L3 Cell Rendering</Td><Td>根據 meta.type 自動選 Display 元件</Td><Td mono>cell-registry.tsx cellRegistry 註冊 11 型:string/number/currency/date/time/select/multiSelect/person/multiPerson/boolean/url(column-types.ts 管 type union + 對齊預設)</Td></tr>
+                <tr><Td>L3 Cell Rendering</Td><Td>根據 meta.type 自動選對應 Cell 元件</Td><Td mono>cell-registry.tsx cellRegistry 註冊 11 型:string/number/currency/date/time/select/multiSelect/person/multiPerson/boolean/url(column-types.ts 管 type union + 對齊預設)</Td></tr>
                 <tr><Td>L4 Interactions</Td><Td>排序 / 選取 / 欄位拖動 / frozen column</Td><Td>TanStack Table features + 自訂 state</Td></tr>
               </tbody>
             </table>
@@ -132,7 +133,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)。display 態零恆顯 chevron(2026-07-08 A 案,editable affordance = hover outline);edit 態才有控件 chrome' },
+    inlineEdit: { control: 'boolean', description: 'inline edit 視覺:cell 間加垂直分隔線(dtCellGrid)。view 態零恆顯 chevron(2026-07-08 A 案,editable affordance = hover outline);edit 態才有控件 chrome' },
     height: {
       control: 'select',
       options: ['auto', '300px'],
@@ -182,7 +183,7 @@ export const ColumnTypes: Story = {
       <div className="flex flex-col gap-8">
         <div>
           <H3>meta.type 系統</H3>
-          <Desc>每個 column 透過 `meta.type` 宣告資料類型,DataTable 自動選擇對應 Field Control 的 `mode="display"` 渲染——消費者不需要手寫 cell。</Desc>
+          <Desc>每個 column 透過 `meta.type` 宣告資料類型,DataTable 自動選擇對應 Field Control 的 `mode="view"` 渲染——消費者不需要手寫 cell。</Desc>
           <DataTable columns={columns} data={SAMPLE_DATA} height="auto" />
         </div>
 
@@ -190,21 +191,21 @@ export const ColumnTypes: Story = {
           <H3>支援的 Column Types</H3>
           <div className="overflow-x-auto">
             <table className="text-caption border-collapse">
-              <thead><tr><Th>meta.type</Th><Th>Display 渲染</Th><Th>對齊</Th><Th>典型場景</Th></tr></thead>
+              <thead><tr><Th>meta.type</Th><Th>view 渲染</Th><Th>對齊</Th><Th>典型場景</Th></tr></thead>
               <tbody>
-                <tr><Td mono>string</Td><Td mono>{`<Input mode="display">`}</Td><Td>left</Td><Td>姓名、title、slug</Td></tr>
-                <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">`}(勾 / 叉 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>string</Td><Td mono>{`<Input mode="view">`}</Td><Td>left</Td><Td>姓名、title、slug</Td></tr>
+                <tr><Td mono>number</Td><Td mono>{`<NumberInput mode="view">`}</Td><Td>right</Td><Td>數量、年齡</Td></tr>
+                <tr><Td mono>currency</Td><Td mono>{`<NumberInput mode="view">`}(+ prefix)</Td><Td>right</Td><Td>金額、價格</Td></tr>
+                <tr><Td mono>date</Td><Td mono>{`<DatePicker mode="view">`}</Td><Td>left</Td><Td>日期、時間戳</Td></tr>
+                <tr><Td mono>boolean</Td><Td mono>{`<Checkbox mode="view">`}(勾 / 叉 icon)</Td><Td>left</Td><Td>啟用 / 可見</Td></tr>
+                <tr><Td mono>select</Td><Td mono>{`<Select mode="view">`}</Td><Td>left</Td><Td>狀態、類別</Td></tr>
+                <tr><Td mono>multiSelect</Td><Td mono>{`<Combobox mode="view">`}</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>
-                <tr><Td mono>url</Td><Td mono>{`<LinkInput mode="display">`}</Td><Td>left</Td><Td>URL</Td></tr>
+                <tr><Td mono>url</Td><Td mono>{`<LinkInput mode="view">`}</Td><Td>left</Td><Td>URL</Td></tr>
               </tbody>
             </table>
           </div>
-          <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>
+          <p className="text-footnote text-fg-muted mt-3">擴充新 type:在 `cell-registry.tsx` 的 `cellRegistry` map 註冊對應 Cell component(view/edit 渲染 SSOT);`column-types.ts` 只設 `align` / default metadata。兩處對齊後自動跟所有 DataTable 整合</p>
         </div>
       </div>
     )
@@ -419,14 +420,14 @@ export const ColorMatrix: Story = {
           選取狀態由 __select__ 欄的 checkbox / radio 呈現,不套 row 底色;hover 與 selection 正交
           (已選 row 仍可有 hover 的 neutral-hover tint,但不疊額外 selected 底色)。
           isRowSelectable=false 僅 disable checkbox,row 不灰底(spec 禁止事項);
-          cell-level disabled(inline edit cellDisabled)才套 --bg-disabled。
+          （2026-07-16 cell disabled 態已廢除,cell 不再套 --bg-disabled;鎖定改用 editable=false 純 view 態）。
         </p>
       </div>
 
       <div>
-        <H3>Cell 內 Display element 色彩</H3>
+        <H3>Cell 內 view element 色彩</H3>
         <Desc>
-          Cell 內的資料元件(Tag / Person / Link / NumberDisplay)各自維持 Field Controls 的 display 色彩。
+          Cell 內的資料元件(Tag / Person / Link / NumberDisplay)各自維持 Field Controls 的 view 色彩。
           DataTable 不覆寫 cell 內的色彩 token,維持跨元件視覺統一。
         </Desc>
         <div className="overflow-x-auto">
@@ -434,7 +435,7 @@ export const ColorMatrix: Story = {
             <thead>
               <tr>
                 <Th>meta.type</Th>
-                <Th>Display 色彩</Th>
+                <Th>view 色彩</Th>
               </tr>
             </thead>
             <tbody>
@@ -463,7 +464,7 @@ export const EmptyState: Story = {
     return (
       <div>
         <H3>無資料時消費 Empty primitive</H3>
-        <Desc>DataTable 的 empty state 走共用 `Empty` 元件——保持跟其他空狀態(SelectMenu、Combobox、Page section)視覺一致。Consumer 不需自訂,自動顯示標準空狀態。</Desc>
+        <Desc>DataTable 的 empty state 走共用 `Empty` 元件——保持跟其他空狀態(SelectMenu、Combobox、Page section)視覺一致。未傳 `emptyState` 時顯示下方的標準 fallback;正式產品應傳 `emptyState` 以業務語言說明「缺什麼資料 + 下一步」,避免抽象的「沒有資料」(對齊 Empty 文案準則)。</Desc>
         <DataTable columns={columns} data={[]} height="auto" />
       </div>
     )

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

@@ -133,9 +133,8 @@
    (在 cell content 之下),non-overlay。Per codex Q1 verdict 對齊 row selected idiom
    `--primary-subtle`(`data-table.spec.md`「L2 選取」段;原引 L170-174 之 selected-row bg 語意 2026-05-31 已廢除,改指現行段)。
    Layer 不再畫 RangeFill div(避免 layer fixed positioned bg 蓋 cell content)。 */
-/* 2026-05-13 V1.6 fix(codex caught medium severity):disabled cell bg dominance — disabled cell
-   included in spreadsheet range 不該被 range fill 蓋過,disabled state visual 必勝。 */
-[data-range-cell]:not([data-cell-disabled="true"]) {
+/* range fill bg(2026-07-16:cell disabled 態已廢除,原 `:not([data-cell-disabled])` exclusion 移除)。 */
+[data-range-cell] {
   background: var(--primary-subtle);
 }
 

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

@@ -4,6 +4,7 @@ import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'
 import { createColumnHelper } from '@tanstack/react-table'
 import { DataTable } from './data-table'
+import { Empty } from '@/design-system/components/Empty/empty'
 import './column-types'
 
 const meta: Meta = {
@@ -71,7 +72,7 @@ export const UsageGuidance: Story = {
       <p>適合 DataTable 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Components/DataTable/展示" name="數字靠右對齊"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">商品庫存後台 — 單價 / 金額數字靠右對齊</span></LinkTo>
+          <LinkTo kind="Design System/Components/DataTable/設計規格" name="對齊規則（跨產業共識）"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">商品庫存後台 — 單價 / 金額數字靠右對齊</span></LinkTo>
         </li>
         <li>
           <LinkTo kind="Design System/Components/DataTable/展示" name="自動行高"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">商品備註長短不一 — 自動行高撐開列高</span></LinkTo>
@@ -132,22 +133,22 @@ export const ColumnTypeRule: Story = {
     return (
       <div>
         <Rule
-          title="✅ 宣告 `meta.type`,DataTable 自動選對應 Display"
-          note="每個 Field Control 的 `mode='display'` 渲染(`<Input mode='display'>` / `<NumberInput mode='display'>` / `<Checkbox mode='display'>` 等)是該資料類型的唯一真實來源——format 邏輯、對齊、null 顯示都住一份。Consumer 只需宣告 type,不需重複造輪子"
+          title="✅ 宣告 `meta.type`,DataTable 自動選對應 view 渲染"
+          note="每個 Field Control 的 `mode='view'` 渲染(`<Input mode='view'>` / `<NumberInput mode='view'>` / `<Checkbox mode='view'>` 等)是該資料類型的唯一真實來源——format 邏輯、對齊、null 顯示都住一份。Consumer 只需宣告 type,不需重複造輪子"
         >
           <DataTable columns={columns} data={SAMPLE_DATA} height="auto" />
         </Rule>
 
         <Rule
           title="❌ 手寫 cell render 自訂格式化"
-          note="每 column 自己寫 `cell: (info) => ...` 會繞過 `mode='display'` 系統——**格式化邏輯會漂移**。一個 table 的 price 顯示「$2,490」,另一個 table 的 price 顯示「2490」,一個 boolean 顯示勾 icon,另一個 boolean 顯示「是」——整個系統 format 失去一致性"
+          note="每 column 自己寫 `cell: (info) => ...` 會繞過 `mode='view'` 系統——**格式化邏輯會漂移**。一個 table 的 price 顯示「$2,490」,另一個 table 的 price 顯示「2490」,一個 boolean 顯示勾 icon,另一個 boolean 顯示「是」——整個系統 format 失去一致性"
         >
-          <Label warn>除非真的需要 `mode='display'` 無法提供的客製視覺,否則一律走 meta.type 系統。客製化時完全跳過 type 讓 display 渲染不要干預</Label>
+          <Label warn>除非真的需要 `mode='view'` 無法提供的客製視覺,否則一律走 meta.type 系統。客製化時完全跳過 type 讓 view 渲染不要干預</Label>
         </Rule>
 
         <Rule
           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 硬寫"
+          note="新增資料類型(如 `percentage`、`relative-time`)在 `cell-registry.tsx` 的 `cellRegistry` map 註冊對應 Cell component(view/edit 渲染 SSOT);`column-types.ts` 只設 align / default metadata。兩處對齊後自動跟所有 DataTable 整合,不在單一 table 硬寫"
         >
           <Label>讓 column type 系統成為 single source of truth,所有 table 受惠同一次更新</Label>
         </Rule>
@@ -189,7 +190,7 @@ export const VirtualScrollRule: Story = {
 
         <Rule
           title="固定 height 數字 — 大量資料(> 100 筆),啟用 virtualization"
-          note="傳固定高度時 TanStack Virtual 自動啟用——只渲染可見 rows。500 筆資料只渲染 ~20 rows,效能不受資料量影響"
+          note="傳固定高度時 TanStack Virtual 自動啟用——只渲染可見 rows。500 筆資料只渲染 ~20 rows,大幅降低列渲染成本。注意:排序 / 篩選 / 完整 row model 與記憶體成本仍隨資料量增長——超大量或遠端資料仍需分頁或 server-side 排序 / 篩選"
         >
           <DataTable columns={columns} data={bigData} height="400px" />
           <Label>↑ 500 筆資料,固定 400px 高度 → virtualizer 只渲染畫面中的 ~20 rows</Label>
@@ -218,10 +219,15 @@ export const EmptyStateRule: Story = {
       <div>
         <Rule
           title="✅ 無資料 → 消費 Empty primitive(跟系統統一)"
-          note="DataTable empty state 走共用 `Empty` 元件——保持跟 SelectMenu / Combobox / Page section 視覺一致。Consumer 不自訂,自動顯示標準空狀態"
+          note="DataTable empty state 走共用 `Empty` 元件——保持跟 SelectMenu / Combobox / Page section 視覺一致。「不自訂」指不手刻自家 empty 視覺,不是省略文案:正式產品應傳 `emptyState` 以業務語言說明「缺什麼資料 + 下一步」(對齊 Empty 文案準則);未傳時才落回抽象 fallback「沒有資料」"
         >
-          <DataTable columns={columns} data={[]} height="auto" />
-          <Label>↑ DataTable 內部自動消費 Empty primitive</Label>
+          <DataTable
+            columns={columns}
+            data={[]}
+            height="auto"
+            emptyState={<Empty title="尚無商品" description="點擊上方「新增商品」開始建立第一筆" />}
+          />
+          <Label>↑ 傳 `emptyState` 消費 Empty primitive,並以業務語言描述缺什麼資料</Label>
         </Rule>
 
         <Rule
@@ -248,7 +254,7 @@ export const NotSpreadsheetRule: Story = {
     <div>
       <Rule
         title="DataTable 預設不做公式計算、不做跨 cell 選取"
-        note="DataTable 的心智模型是「結構化資料展示」——每筆資料是一 row,每個屬性是一 column。預設不做:Excel 的公式、跨 cell range selection(Ctrl+drag)、cell clipboard paste、pivot、跨欄運算。**逃生門**:確需 Excel-like 編輯可 opt-in `spreadsheetMode` prop(Shift+click range + 方向鍵 cell 導覽 + cell editing;仍不做公式計算),對齊 spec.md L28。"
+        note="DataTable 的心智模型是「結構化資料展示」——每筆資料是一 row,每個屬性是一 column。預設不做:Excel 的公式、跨 cell range selection(Ctrl+drag)、cell clipboard paste、pivot、跨欄運算。**逃生門**:確需 Excel-like 編輯可 opt-in `spreadsheetMode` prop(Shift+click range + 方向鍵 cell 導覽 + cell editing;仍不做公式計算)——即使開啟 spreadsheetMode,DataTable 仍只是「可 range 選取 + 方向鍵導覽 + inline 編輯」的結構化資料表,不會變成有公式引擎的試算表。"
       >
         <Label>需要試算表能力 → 用專門 library(AG Grid Enterprise / Handsontable / Luckysheet),不往 DataTable 塞</Label>
       </Rule>

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

@@ -72,7 +72,7 @@ DataTable 有三種尺寸（`sm`、`md`、`lg`），透過 `size` prop 控制。
 
 水平 padding 固定,不隨 size 或 density 變化(具體 token 見 `data-table.tsx`);垂直方向由行高模式決定(見第四節)。
 
-**Cell / header 字級隨 size,對齊 Field family。** 三種 size 的 cell 與 header 預設字級**必與同 size 的 Field 一致**:`sm`/`md` → `text-body`(14px)、`lg` → `text-body-lg`(16px),SSOT = `fieldDisplayTextClass()`(`field-wrapper.tsx`)。`lg` 行高放大時字級同步放大,避免「字小、行高大」失衡。**機制**:typed cell 由各自 Field 控件吃 `size` 自動套用(cell-registry 各 cell display mode 必傳 `size`,**禁漏傳**否則 fallback md 卡 14px);header 與非-Field 內容(consumer 自訂 cell)由 cell wrapper / header `cn(fieldDisplayTextClass(size))` 套用。`1lh`-based cell-py 公式(見第四節)隨字級自動吸收,row 高不變。
+**Cell / header 字級隨 size,對齊 Field family。** 三種 size 的 cell 與 header 預設字級**必與同 size 的 Field 一致**:`sm`/`md` → `text-body`(14px)、`lg` → `text-body-lg`(16px),SSOT = `fieldDisplayTextClass()`(`field-wrapper.tsx`)。`lg` 行高放大時字級同步放大,避免「字小、行高大」失衡。**機制**:typed cell 由各自 Field 控件吃 `size` 自動套用(cell-registry 各 cell view mode 必傳 `size`,**禁漏傳**否則 fallback md 卡 14px);header 與非-Field 內容(consumer 自訂 cell)由 cell wrapper / header `cn(fieldDisplayTextClass(size))` 套用。`1lh`-based cell-py 公式(見第四節)隨字級自動吸收,row 高不變。
 
 ### 二、高度模式(有高度約束 vs 無高度約束,決定可用的功能組合)
 
@@ -120,7 +120,7 @@ Table 層級的模式切換，不是 column 層級。跟 AG Grid / Airtable 的
 
 ### 六之二、Column 寬度 API + 不變條件(2026-05-06 v14.3)
 
-**命名**:`meta.width` / `meta.minWidth` / `meta.maxWidth`(px)。**不用 TanStack `size`** — DS 內 `size` 既定為 `'sm'|'md'|'lg'` density(49+ 處),避 namespace 衝突。內部 pre-process copy 到 TanStack root,resize feature 正常。No-resize default:`width` = reserve(cell ≥ width,flex 可 grow,不可 shrink)。`enableColumnResize=true`:`width` = 初始,`minWidth` = 拖拉下限(default 80)。**不變條件(invariants,L2 test + hook 守)**:(1) cell width = column width(跟 padding/state/mode 無關)(2) display↔edit cell width 0 delta (3) display↔edit cell height 0 delta(textarea `field-sizing:content`)(4) Field 填滿 cell 高度(1px 容差於 cell.border-r)(5) No-resize column ≥ meta.width。對應 `scripts/data-table-invariants.mjs`。改 `columnSizeStyle` / 切 layout 必跑 invariant test 才 commit。
+**命名**:`meta.width` / `meta.minWidth` / `meta.maxWidth`(px)。**不用 TanStack `size`** — DS 內 `size` 既定為 `'sm'|'md'|'lg'` density(49+ 處),避 namespace 衝突。內部 pre-process copy 到 TanStack root,resize feature 正常。No-resize default:`width` = reserve(cell ≥ width,flex 可 grow,不可 shrink)。`enableColumnResize=true`:`width` = 初始,`minWidth` = 拖拉下限(default 80)。**不變條件(invariants,L2 test + hook 守)**:(1) cell width = column width(跟 padding/state/mode 無關)(2) view↔edit cell width 0 delta (3) view↔edit cell height 0 delta(textarea `field-sizing:content`)(4) Field 填滿 cell 高度(1px 容差於 cell.border-r)(5) No-resize column ≥ meta.width。對應 `scripts/data-table-invariants.mjs`(script 內 I1-I3 label 字串仍用 `display↔edit` — 2026-07-16 FieldMode display→view 更名前的歷史命名,語意同 view↔edit)。改 `columnSizeStyle` / 切 layout 必跑 invariant test 才 commit。
 
 ### 六之三、Runtime perf budget canonical(2026-05-14 codex+Layer A)
 
@@ -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(自動繼承)。**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 分流表) |
+| Body cell internal(view endAction / clear / edit indicator)| Field family endAction(自動繼承)。**View 態零恆顯型別 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 共識) |
 
@@ -180,7 +180,7 @@ Cell 已 `flex items-center`,consumer render 直接 inline-flex + gap-2。Icon s
 
 ### 十一、Cell 單行截斷原則
 
-固定行高下 cell 單行,空間不足:純文字 `text-overflow: ellipsis`;Tag 文字內部 truncate(Tag bg 跟縮);multiSelect 動態 `+N`;Person avatar 不縮 name truncate;Link truncate。每個 Display 元件自管 truncation,Cell `overflow-hidden` 僅 safety net。截斷必顯 `...`(禁硬裁無 ellipsis)。截斷 hover 顯 tooltip。autoRowHeight wrap 模式不適用(可換行撐 row 高)。
+固定行高下 cell 單行,空間不足:純文字 `text-overflow: ellipsis`;Tag 文字內部 truncate(Tag bg 跟縮);multiSelect 動態 `+N`;Person avatar 不縮 name truncate;Link truncate。每個 view 態元件自管 truncation,Cell `overflow-hidden` 僅 safety net。截斷必顯 `...`(禁硬裁無 ellipsis)。截斷 hover 顯 tooltip。autoRowHeight wrap 模式不適用(可換行撐 row 高)。
 
 ### 十二、可推導值用 `calc()` 表達(不硬寫結果)— 上游動,下游自動跟著算
 
@@ -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):
 
@@ -442,9 +442,9 @@ Row drag + column reorder + TreeView 共用 `lib/drag-visual.ts`:source `opacity
 
 ## Overlay + cell error SSOT(Phase 9)
 
-**Overlay**:viewport `position:fixed inset:0` layer。`getCellRect()` 從 `getBoundingClientRect()` 取 float coords no rounding。Paint:hover/selected ring `outline outline-offset:-1px` in-place(range outer ring 已 2026-05-10 retire — range 視覺只剩 cell-bg `--primary-subtle` `[data-range-cell]`,bg 已足以標示範圍、外框冗餘);active editor host portal opaque `<div>` z 3(cell 保持 display)。**Viewport clip**(Issue 6):body panel 加 `data-datatable-panel="left|center|right"`;`getCellGeometry()` return cell+panel rect;`<ClipMask>` panel rect `overflow:hidden`,內部 `toRelRect()` 轉 mask-relative(hover/selected ring 按 panel clip,不畫出 pin boundary)。Active editor host **不 clip**。對齊 AG Grid `cellsForRangeSet` / Glide / Notion sticky-cell mask。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Overlay**:viewport `position:fixed inset:0` layer。`getCellRect()` 從 `getBoundingClientRect()` 取 float coords no rounding。Paint:hover/selected ring `outline outline-offset:-1px` in-place(range outer ring 已 2026-05-10 retire — range 視覺只剩 cell-bg `--primary-subtle` `[data-range-cell]`,bg 已足以標示範圍、外框冗餘);active editor host portal opaque `<div>` z 3(cell 保持 view 態)。**Viewport clip**(Issue 6):body panel 加 `data-datatable-panel="left|center|right"`;`getCellGeometry()` return cell+panel rect;`<ClipMask>` panel rect `overflow:hidden`,內部 `toRelRect()` 轉 mask-relative(hover/selected ring 按 panel clip,不畫出 pin boundary)。Active editor host **不 clip**。對齊 AG Grid `cellsForRangeSet` / Glide / Notion sticky-cell mask。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-**Cell errors**(Issue 9):`cellErrors?: Record<string, string|string[]>` prop key `${rowId}:${colId}`。Cell display 渲 error 14px `text-error` 下方 gap-1;array→`<ul><li>`;single→`<span>`。`aria-describedby` + `aria-invalid` + `<span role="alert">`。`overflow:visible` 當有 error(搭 `autoRowHeight`)。**Per-row state SSOT** cell-render wrapper(`items-X` 等)必 consume `effectiveAutoRowForCell`,禁 global `autoRowHeight`(audit `audit-data-table-row-mode-ssot.mjs` 強制)。**Edit-clears-own-cell** 自動清視覺,consumer onCellCommit validate 後回填。**a11y caveat**:≥ 5 同時 `role="alert"` 第一次 paint AT 噪音 → consumer 可考 `role="status"` fallback。對齊 AG Grid `cellClassRules='ag-cell-error'` + Material X errorMessage + Airtable validation。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Cell errors**(Issue 9):`cellErrors?: Record<string, string|string[]>` prop key `${rowId}:${colId}`。Cell view 態渲 error 14px `text-error` 下方 gap-1;array→`<ul><li>`;single→`<span>`。`aria-describedby` + `aria-invalid` + `<span role="alert">`。`overflow:visible` 當有 error(搭 `autoRowHeight`)。**Per-row state SSOT** cell-render wrapper(`items-X` 等)必 consume `effectiveAutoRowForCell`,禁 global `autoRowHeight`(audit `audit-data-table-row-mode-ssot.mjs` 強制)。**Edit-clears-own-cell** 自動清視覺,consumer onCellCommit validate 後回填。**a11y caveat**:≥ 5 同時 `role="alert"` 第一次 paint AT 噪音 → consumer 可考 `role="status"` fallback。對齊 AG Grid `cellClassRules='ag-cell-error'` + Material X errorMessage + Airtable validation。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ---
 
@@ -492,7 +492,7 @@ DataTable 是 composite multi-section 元件,**不套 SizeMatrix / StateBehavior
 
 **Keyboard 行為**(目前實作 — `tableKeyboardHandler`):
 - ↑↓←→:cell-to-cell navigation **僅 `spreadsheetMode` opt-in 時生效**;selection 尚未建立時按方向鍵自動選取第一個 visible cell(鍵盤可直接進入 spreadsheet 導覽,無需滑鼠 click — 對齊 Excel / Google Sheets / AG Grid「focus grid → first cell active」,2026-07-05 D4 補);預設模式方向鍵無作用
-- Enter / F2:spreadsheet 模式下進 cell editing(cell 可編輯 + 非 boolean/url + 非 disabled 時);**Enter 確認後維持原格不下移**(2026-07-05 user 拍板;10 家實查:Excel 系 7 家下移、AG Grid 預設維持原格 — 採 AG Grid 派,數據 → `.claude/logs/deep-audit-2026-07-03/enter-commit-navigation-benchmark.json`;未來連續輸入需求可重議 opt-in);**edit 退出(commit / Esc)後 selection 還原至該 cell、焦點還給 table root**(editor unmount 後焦點掉到 body 才收回,不搶 user 點擊的新焦點 — 對齊 spreadsheet RFC Contract 11 + Excel / AG Grid,2026-07-05 D4 補)
+- Enter / F2:spreadsheet 模式下進 cell editing(cell 可編輯 + 非 boolean/url 時);**Enter 確認後維持原格不下移**(2026-07-05 user 拍板;10 家實查:Excel 系 7 家下移、AG Grid 預設維持原格 — 採 AG Grid 派,數據 → `.claude/logs/deep-audit-2026-07-03/enter-commit-navigation-benchmark.json`;未來連續輸入需求可重議 opt-in);**edit 退出(commit / Esc)後 selection 還原至該 cell、焦點還給 table root**(editor unmount 後焦點掉到 body 才收回,不搶 user 點擊的新焦點 — 對齊 spreadsheet RFC Contract 11 + Excel / AG Grid,2026-07-05 D4 補)
 - Cmd/Ctrl+A:`mode="multi"` selection 時選全可見列(扣 disabled)
 - Esc:取消 editing(spreadsheet)/ 清 selection(selection mode);**IME 組字中的 Enter / Esc 不觸發 commit / cancel**(cell editor 帶 `isComposing` guard,2026-07-05 D4 補 — 中文選字 Enter 不誤提交半截組字)
 - Tab:進入表格後操作排序與勾選;portal edit(`experimentalActiveEditorController`)中 Tab / Shift+Tab = commit 當前 draft + 移至下一個 editable cell 進 edit(2026-07-05 D4 補 commit — 原本換格丟 draft)