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

package/src/components/Empty/empty.tsx

@@ -13,7 +13,9 @@ import { useRowSize } from '@/design-system/patterns/element-anatomy/item-anatom
  * 間距固定,不隨 density 變（Empty 是展示性元件,不是工作區域元件）:
  *   icon → text = mb-4（16px）
  *   desc → action = mt-6（24px）
- *   title → desc = `var(--item-gap-label-desc)`（token,預設 2px,item-anatomy SSOT）
+ *   title → desc = `var(--item-gap-label-desc-reading-lg)`（reading-lg tier token,item-anatomy SSOT;bare `--item-gap-label-desc` 已 retire）
+ *
+ * description 字級隨 RowSizeContext 變（sm/md → text-body 14px,lg → text-body-lg 16px）。
  *
  * Outer padding 由 consumer 容器決定(py-12 / py-6 / py-16 等）。
  */
@@ -27,10 +29,16 @@ export interface EmptyProps extends React.HTMLAttributes<HTMLDivElement> {
   description?: string
   /** 行動按鈕(可選) */
   action?: React.ReactNode
+  /**
+   * Disabled context(2026-06-03 加 — FileUpload disabled 等情境消費):title / description 轉
+   * `text-fg-disabled`(語意 disabled token,非 opacity)。icon glyph 也 → fg-disabled(icon 是文字一環);icon-circle bg 維持 muted。
+   * 預設 false,不影響既有 consumer。
+   */
+  disabled?: boolean
 }
 
 const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
-  ({ icon, title, description, action, className, ...props }, ref) => {
+  ({ icon, title, description, action, disabled = false, className, ...props }, ref) => {
     // 字體 tier:讀 RowSizeContext(menu 內自動對齊 menu items 的字體）
     // 沒有 context(standalone）→ fallback 'md' → text-body (14px)
     const rowSize = useRowSize('md')
@@ -45,7 +53,8 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
         iconElement = icon
       } else {
         const Icon = icon as LucideIcon
-        iconElement = <Avatar icon={Icon} size={48} color="neutral" />
+        // disabled:glyph → fg-disabled([&_svg]:!… 蓋過 Avatar 內聯 color;circle bg 維持 muted)。icon 是文字一環,隨 disabled 變淡。
+        iconElement = <Avatar icon={Icon} size={48} color="neutral" className={disabled ? '[&_svg]:!text-fg-disabled' : undefined} />
       }
     }
 
@@ -59,7 +68,7 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
           <div className="mb-4">{iconElement}</div>
         )}
         {title && (
-          <span className="text-body-lg font-medium text-foreground">
+          <span className={cn('text-body-lg font-medium', disabled ? 'text-fg-disabled' : 'text-foreground')}>
             {title}
           </span>
         )}
@@ -69,7 +78,7 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
               // 字體跟 RowSizeContext 對齊:sm/md = text-body (14px),lg = text-body-lg (16px)
               // 在 menu 內自動對齊 menu items;standalone 時 fallback text-body
               descFont,
-              (title || action) ? 'text-fg-secondary' : 'text-fg-muted',
+              disabled ? 'text-fg-disabled' : (title || action) ? 'text-fg-secondary' : 'text-fg-muted',
               // Empty title 永遠 body-lg(16)→ 用 reading-lg token(label tier 決定)
               title && 'mt-[var(--item-gap-label-desc-reading-lg)]',
             )}
@@ -97,10 +106,10 @@ export const emptyMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default', 'disabled'],
   tokens: {
     bg: [],
-    fg: ['text-fg-muted', 'text-fg-secondary', 'text-foreground'],
+    fg: ['text-fg-muted', 'text-fg-secondary', 'text-foreground', 'text-fg-disabled'],
     ring: [],
   },
 } as const

package/src/components/Empty/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './empty'

package/src/components/Field/field-context.ts

@@ -134,3 +134,101 @@ export function TableScrollProvider({
 }): React.ReactElement {
   return React.createElement(TableScrollContext.Provider, { value: isScrolling }, children)
 }
+
+/**
+ * Surface size signal — 獨立於 FieldContext + FieldSurfaceContext 的純視覺 size context(2026-06-08)。
+ * 讓 host(DataTable cell substrate)把「這片 surface 的 density size」propagate 給 child Field controls,
+ * 未來新 cell 漏傳 size prop 也自動繼承 → 字級一致(根治 StringCell/NumberCell 漏傳 size class)。
+ *
+ * 不放進 FieldSurfaceContext value(避免 string→object identity drift on scroll → 全 cell 重渲,
+ * 同 TableScrollContext L119-121 canonical)— 獨立 Context,value = FieldSize primitive(stable when unchanged)。
+ * 絕不污染 FieldContext:不碰 hasFieldWrapper/mode/invalid/disabled,useFieldContext() 在 cell 內仍 null。
+ */
+const FieldSurfaceSizeContext = React.createContext<FieldSize | null>(null)
+
+/**
+ * Resolve Field control size — 控件用此 helper 取代散落的 `sizeProp ?? fieldCtx?.size ?? 'md'`。
+ * 優先序:prop(caller 顯式)> FieldContext.size(真 <Field> wrapper)> surface-size(host 如 cell)> 'md'。
+ * 真 <Field> 永遠勝 host surface(安全序);cell 無 Field wrapper(fieldCtx=null)→ 自動接 surface-size,
+ * 漏傳 size 的新 cell 也字級一致。
+ */
+export function useResolvedFieldSize<T extends string = FieldSize>(sizeProp?: T | null, fallback?: T): T {
+  const fieldCtx = React.useContext(FieldContext)
+  const surfaceSize = React.useContext(FieldSurfaceSizeContext)
+  // generic T(預設 FieldSize)讓非-input 控件(SegmentedControl/Rating 的 'xs'|'sm'|'md'|'lg' 超集、各自 fallback)
+  // 也走同一 SSOT resolution。fieldCtx.size/surfaceSize 為 FieldSize(T 的子集)→ widen cast 安全。
+  // fallback 未傳預設 'md'(input-class 控件向後相容);Rating 傳 'xs'、SegmentedControl 傳 'md'。
+  return (sizeProp ?? (fieldCtx?.size as T | undefined) ?? (surfaceSize as T | undefined) ?? fallback ?? ('md' as T))
+}
+
+/**
+ * Resolve Field control 的 **disabled** — 取代散落的 `disabledProp ?? fieldCtx?.disabled`(2026-06-08 SSOT)。
+ * 優先序:顯式 prop > FieldContext.disabled(`<Field disabled>` / `<Field mode="disabled">`)> false。
+ * **caller 必傳「未預設」的原始 prop**(沒傳 = undefined),否則 `disabled=false` 預設會吃掉 `??` fallback。
+ * DataTable cell 無 FieldContext(fieldCtx=null)→ 回 prop 或 false,行為與現況完全一致(inert)。
+ */
+export function useResolvedFieldDisabled(disabledProp?: boolean | null): boolean {
+  const fieldCtx = React.useContext(FieldContext)
+  return disabledProp ?? fieldCtx?.disabled ?? false
+}
+
+/**
+ * Resolve Field control 的 **mode**(display / readonly / disabled / edit)— 2026-06-08 SSOT,統一兩派散落:
+ *   舊 Input 派 `modeProp ?? fieldCtx?.mode ?? (...)` → `<Field disabled>` 時 ctx.mode 仍 'edit',漏 disabled chrome。
+ *   舊 picker 派 `disabled ? 'disabled' : mode`(mode 預設 'edit')→ 完全不讀 fieldCtx.mode,`<Field mode="display">` 失效。
+ * 統一優先序(world-class:MUI FormControl disabled 完整 cascade + 顯式 prop 永遠最優先):
+ *   1. 顯式 mode prop(caller / DataTable cell 的 displayOrDisabled)→ **永遠最優先**,故表格等顯式場景 inert
+ *   2. 有效 disabled(prop 或 `<Field disabled>`)→ 'disabled'(完整 disabled chrome)
+ *   3. FieldContext.mode(`<Field mode="display"/"readonly">`)→ 讓 mode cascade 真正生效
+ *   4. 本地 readOnly → 'readonly'
+ *   5. 'edit'
+ * cell:mode prop 必有 → step 1 命中、fieldCtx=null → 完全 inert(Δ=0)。`disabled` 傳已 resolve 的 boolean 或未預設 prop。
+ */
+export function useResolvedFieldMode({
+  mode,
+  disabled,
+  readOnly,
+}: {
+  mode?: FieldMode | null
+  disabled?: boolean | null
+  readOnly?: boolean
+}): FieldMode {
+  const fieldCtx = React.useContext(FieldContext)
+  if (mode) return mode
+  if ((disabled ?? fieldCtx?.disabled) === true) return 'disabled'
+  if (fieldCtx?.mode) return fieldCtx.mode
+  if (readOnly) return 'readonly'
+  return 'edit'
+}
+
+/**
+ * Resolve Field control 的 **variant**(default / bare / naked 視覺外殼)— 2026-06-08 SSOT。
+ * 優先序:顯式 prop > FieldContext.variant > 'default'。與既有各控件公式一字不差(Δ=0),統一以利 gate 強制。
+ */
+export function useResolvedFieldVariant(variantProp?: FieldVariant | null): FieldVariant {
+  const fieldCtx = React.useContext(FieldContext)
+  return variantProp ?? fieldCtx?.variant ?? 'default'
+}
+
+/**
+ * Resolve Field control 的 **error/invalid** — 取代散落的 `errorProp || (fieldCtx?.invalid ?? false)`(2026-06-08 SSOT)。
+ * 自身 error prop **或** FieldContext.invalid(`<Field invalid>`)任一為真即 error。與既有公式一致(Δ=0)。
+ */
+export function useResolvedFieldInvalid(errorProp?: boolean): boolean {
+  const fieldCtx = React.useContext(FieldContext)
+  return Boolean(errorProp) || (fieldCtx?.invalid ?? false)
+}
+
+/**
+ * Host(non-Field-wrapper,如 DataTable cell)注 surface density size 給 child Field controls。
+ * 僅注 size 視覺訊號,不污染 FieldContext。Usage:cell-registry buildCellWithSurface。
+ */
+export function FieldSurfaceSizeProvider({
+  size,
+  children,
+}: {
+  size: FieldSize
+  children: React.ReactNode
+}): React.ReactElement {
+  return React.createElement(FieldSurfaceSizeContext.Provider, { value: size }, children)
+}

package/src/components/Field/field-controls.spec.md

@@ -0,0 +1,382 @@
+---
+component: FieldControls
+traits:
+  - hasVariants
+  - hasSizes
+  - hasInteractiveStates
+  - isStructural
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline(M22(d) 顯式撤回;本檔 frontmatter 無 benchmark list,來源 URL 未補)。 -->
+
+# Field Controls 設計原則
+
+> **Foundational SSOT rationale**(cap 800,2026-04-25 approved):
+> Family 4 (Field Control Layout) SSOT owner。Input / NumberInput / DatePicker / Select / Combobox / LinkInput / TimePicker / Textarea / PeoplePicker 等皆消費 `fieldWrapperStyles` / edit-readonly-disabled 三態 mode architecture / endAction 處理 / `mode="display"` 渲染 pattern / Inline Action canonical(後者也 cascade 到 Sidebar / TreeView / DropdownMenu)。scope 本質 > 單一元件。
+
+> **注意**：此文件是 Field Controls（Input / NumberInput / DatePicker / Select / Combobox / LinkInput / PeoplePicker 等)**共用**的設計原則，與 `Field/field.spec.md`（表單 Layout 容器）**不是同一個東西**。
+>
+> - **Field Controls**（本文件）：具體的資料型別輸入元件，內部含 edit/readonly/disabled 三態 + 格式化 + DataTable Display 共用
+> - **Field**（`Field/field.spec.md`）：shadcn 風格的表單 Layout 容器（label + description + error），wrap 上述 Field Controls 元件
+
+**Layout Family**：本 spec 是 CLAUDE.md 4-Family Model **Family 4（Field Control Layout）的 SSOT**。結構 `fieldWrapperStyles + [startIcon?] [<editable content>] [endAction?]`，**視覺對齊 Family 1（Menu item layout）**——Select trigger 的高度 / 字體 / icon size 必須跟其 SelectMenu options 連續一致。Consumers: Input（canonical）, NumberInput, DatePicker, Select, Combobox, LinkInput, PeoplePicker。
+
+## 定位
+
+Field Controls 是資料輸入與顯示的基礎元件。每種資料類型（text、number、date、select...）對應一個元件，同時服務 Form 和 DataTable：
+
+- **Form**：用 Field Controls 的 edit / readonly / disabled 三態（在 Field 容器內）
+- **DataTable**:以 Field Controls 的 `mode="display"` 渲染 cell
+
+每個元件擁有該類型的格式化邏輯（唯一真實來源），Form 和 DataTable 消費同一份 code。
+
+---
+
+## 架構
+
+```
+components/
+├── Field/
+│   ├── field.tsx               ← Field 佈局容器(label + control + desc + error)
+│   ├── field.spec.md           ← Field 佈局容器設計原則
+│   ├── field-controls.spec.md  ← 本文件
+│   ├── field-types.ts          ← FieldMode / FieldVariant 共用型別 + getMenuListMinHeight(InlineActionConfig 住 patterns/element-anatomy/item-anatomy.tsx)
+│   └── field-wrapper.tsx       ← 共用 wrapper 樣式、bareInputStyles、EMPTY_DISPLAY
+├── Input/                      ← Input(含 mode="display";與 Field 平行的兄弟目錄,以下同)
+├── NumberInput/                ← NumberInput(含 mode="display" + formatNumber)
+├── DatePicker/                 ← DatePicker(含 mode="display" + formatDate)
+├── Select/                     ← Select(含 mode="display")
+├── Combobox/                   ← Combobox(含 mode="display")
+├── LinkInput/                  ← LinkInput(含 mode="display")
+├── PeoplePicker/               ← PeoplePicker + PersonDisplay(cross-component primitive)
+└── Textarea/                   ← Textarea(多行)
+```
+
+每個元件統一以 `mode` prop 切換樣態：
+1. **edit / readonly / disabled** — Form 用，可編輯 / 鎖定 / 不可用
+2. **`mode="display"`** — DataTable cell 用，純格式化顯示（取代過往的 `XxxDisplay` 子元件）
+
+---
+
+## Mode — 表單三態 (display 見下方 Display 段)
+
+下表涵蓋 Form-context 三態(edit / readonly / disabled);完整 `FieldMode` 為四值(`'edit' | 'display' | 'readonly' | 'disabled'`),`display` 模式於下方 `## Display` 段記載。
+
+| Mode | 底色 | 邊框 | 文字色 | 用途 |
+|------|------|------|--------|------|
+| `edit` | surface | border（hover 深一階、focus primary） | foreground | 表單可編輯欄位 |
+| `readonly` | neutral-2(`--bg-readonly`)| 無 | foreground | 表單中不可編輯但可見的欄位 |
+| `disabled` | neutral-2(`--bg-disabled`)| 無 | fg-disabled | 表單中被停用的欄位 |
+
+三種模式共用同一個 wrapper 結構（`fieldWrapperStyles`），只有底色、邊框、文字色不同。
+
+**Boolean / 單選控件的 readonly(2026-06-12 user 拍板)**:Field 內 readonly 的 Checkbox / Switch = 同一 `fieldWrapperStyles` readonly 灰框 + ✓/—(display 同款值語言);RadioGroup = 灰框 + 選中項 label(= Select readonly 同款呈現)。理由:同一張 readonly 表單中,文字控件有灰框鎖定訊號、boolean 保留全彩控件會誤導「仍可操作」(世界級 0/4 採原樣鎖互動:Salesforce = ✓ 無框靜態 glyph / SAP = 靜態文字 / Atlassian = readView / Ant Pro = 文字)。standalone readOnly(settings list / SelectionItem row)維持原樣鎖互動。**邊界**:Rating readonly = 星星本身(星星即值語言,role=img,全業界 review-stars canonical,不包灰框);Slider 在 `<Field mode="readonly">` 內 = 鎖互動保留正常視覺(value 可讀不降色,pointer-events-none + thumb tabIndex=-1)。
+
+### Loading state(async 驗證 / debounce fetch 中)
+
+Loading **不是第四個 mode**,是 `edit` mode 的子狀態,語義 = **editable 仍可輸入**(UX「邊改邊讀」:debounce search / async validation 場景中 user 常需要繼續打字修正,凍結輸入反而破壞心流)。
+
+**世界級流派選擇**(editable 派 vs readonly 派):
+
+| DS | Loading input 做法 | 流派 |
+|----|-------------------|------|
+| Ant Input.Search | **input 仍 editable**,suffix spinner;submit 另鎖 | editable |
+| Material TextField | readonly + suffix adornment loader | readonly |
+| Polaris TextField | readonly + helpText 提示 | readonly |
+| Carbon TextInput | readonly + inline Loading | readonly |
+| Atlassian TextField | disabled | disabled(少數派) |
+| Apple HIG UITextField | visual overlay only,不阻礙輸入 | editable |
+
+**本 DS 採 editable 派**(Ant / Apple HIG):
+- **UX 理由**:debounce 搜尋場景,user 邊打邊看建議,凍結一格會卡節奏;async validation 若第一次失敗,user 該能立即改,不是等 spinner 完才能動
+- **對照 readonly 派**:readonly 派適合「提交後驗證」的場景(e.g. 表單 submit → 驗證),本 DS 的 `loading` prop 用在 debounce / inline validation,editable 更 fit
+
+**實作 canonical(Input / Combobox 等具 async 語意的 Field 元件;NumberInput 不提供 loading——見 `number-input.spec.md`「Loading」)**:
+- API:`loading?: boolean` prop
+- 內部:`loading=true` → wrapper `aria-busy="true"` + **endAction slot 自動塞 `<CircularProgress size={iconSize}/>`**(與 `endAction` prop 互斥,loading 優先)
+- input **不進 readonly / disabled**,保持可編輯
+- CircularProgress 尺寸:程式化 `iconSize`(sm/md=16, lg=20),消費者不用再傳
+- CircularProgress 顏色:走預設 `text-primary`(表達「正在處理,請注意」)
+- startIcon(Search 等語義 icon)**不受 loading 影響**,保留原位置
+
+```tsx
+// 世界級 canonical:search field 在 loading 中,user 仍可修改關鍵字
+<Input startIcon={Search} loading placeholder="搜尋..." />
+// → search icon 在 prefix(保留語義身分)
+// → CircularProgress 在 endAction 位置(暫時狀態)
+// → input editable + aria-busy,user 可繼續輸入 / 修改
+```
+
+❌ 禁止手刻路線:
+```tsx
+// 絕對不寫
+<div className="relative">
+  <Input startIcon={Search} />
+  <div className="absolute right-3 top-1/2 -translate-y-1/2">
+    <CircularProgress size={16} />
+  </div>
+</div>
+```
+手刻 absolute 對齊容易跑掉(Field 元件內 loading 指示與既有 endAction 垂直對齊不一致)。一律用 `loading` prop。
+
+### disabled 的停用原因
+
+停用原因由外部承擔，不在 input 內放 info icon：
+- **Tooltip**：包住整個 Field 元件（wrapper `<div>` 不是 disabled 元素，可正常接收 hover）
+- **Form help text**：在 input 下方說明（Form 層負責）
+
+### 原生屬性與 mode
+
+未顯式傳 `mode` 時,`disabled` / `readOnly` 原生屬性參與 mode 解析(disabled → `'disabled'`,優先於 fieldCtx.mode;readOnly → `'readonly'`,殿後);**顯式 `mode` prop 永遠最優先**,不被原生屬性覆蓋。完整 precedence 見「Field context cascade — SSOT」表。
+
+---
+
+## Error — 正交於 mode
+
+Error 是 boolean prop，獨立於 mode。只在 `edit` 模式下有視覺效果（`border-error`）。
+
+- Error 視覺在 Field（input）層級：紅色邊框 + `aria-invalid`
+- Error 訊息在 Form 層級：help text 顯示在 input 下方
+- Field 不在尾部放狀態 icon（如 ⚠️）——邊框顏色已經傳達了 error 狀態
+
+Form wrapper 可透過 context 注入 `error` prop，消費者不需要在每個 Field 上手動傳。
+
+---
+
+## Field context cascade — SSOT（2026-06-08）
+
+`<Field>` 透過 context 把欄位狀態流給「所有」子控件，控件**不可各自手刻解析邏輯**，一律消費 `field-context.ts` 的 resolver hook（SSOT，precedence 全庫一致）：
+
+| 流下的狀態 | Resolver hook | Precedence |
+|---|---|---|
+| size | `useResolvedFieldSize(prop)` | prop > fieldCtx.size > surface-size > fallback |
+| disabled | `useResolvedFieldDisabled(prop)` | prop > fieldCtx.disabled > false |
+| mode | `useResolvedFieldMode({ mode, disabled, readOnly })` | 顯式 mode prop > 有效 disabled→`'disabled'` > fieldCtx.mode > readOnly > `'edit'` |
+| variant | `useResolvedFieldVariant(prop)` | prop > fieldCtx.variant > `'default'` |
+| error/invalid | `useResolvedFieldInvalid(prop)` | prop OR fieldCtx.invalid |
+
+**precedence 關鍵**：顯式 prop 永遠最優先（故 DataTable cell 顯式傳 mode/size → 完全不受 context 影響）；其次「有效 disabled」（prop 或 `<Field disabled>`）強制 `'disabled'` 完整 chrome（對齊 MUI FormControl「disabled → label/input displayed in a disabled state」）。`<Field disabled>` 只設 `ctx.disabled=true`、`ctx.mode` 仍是 `'edit'`，故控件**必須讀 disabled 而非只讀 mode**，否則 `<Field disabled>` 失效（2026-06-08 PeoplePicker/Switch/Rating/Slider/Avatar 之 cascade bug 根因）。
+
+### 哪些元件吃 `<Field disabled>` cascade（一致判斷標準）
+
+判準 = **「這個元件是不是承載／編輯一個欄位值的互動控件？」**（對齊 MUI FormControl 對 form control 的 cascade、Ant `Form disabled` 排除非表單控件如 Segmented/Tabs）：
+
+- **承載欄位值的互動控件** → 完整 cascade（disabled + 有 display 態者含 mode）：Input / NumberInput / Textarea / LinkInput / Select / Combobox / DatePicker / TimePicker / PeoplePicker / Switch / Checkbox / RadioGroup / Slider / SegmentedControl / Rating。
+- **欄位內的展示元素**（Avatar）→ 跟隨 `<Field disabled>` / `<Field mode="disabled">` **變淡**（視覺一致），用 fieldCtx 存在性 scope（DataTable cell 無 fieldCtx → 不影響）。
+- **獨立 action 元件**（Button）→ **不**自動 cascade；由 consumer 自控 `disabled`（對齊 MUI Button 無 FormControl 整合 + Ant 排除 custom／非表單控件）。
+
+注：有 display 渲染分支者（Input 家族 / Select / Combobox / DatePicker / TimePicker / PeoplePicker / **Checkbox** / **Switch**，後二者 display = ✓/—）完整響應 `<Field mode="display"/"readonly">` + `<Field disabled>`；**Slider / Rating 無 display 態但有 readonly cascade**（2026-06-12 補:Slider readonly = 鎖互動保留視覺;Rating readonly = 星星鎖定 role=img）+ 響應 `<Field disabled>`;**SegmentedControl 無 display/readonly 態**（僅 enabled/disabled）→ 只響應 `<Field disabled>`。**group 控件（Checkbox/RadioGroup/Switch/SegmentedControl）雖非 fieldWrapperStyles 消費者，仍一律經 resolver hook 解析**（gate Check 1b/2 強制）。
+
+**機械強制**：`scripts/check-field-cascade-resolve.mjs`（ci + release:preflight）—— 消費 `fieldWrapperStyles` 的控件若散落手刻 `fieldCtx?.{disabled,mode}` 解析（而非走 resolver hook）= fail，防新控件重演 cascade 漏接。
+
+---
+
+## Size — 與 Button 對齊
+
+| Size | 高度 token | Tailwind | 字體 |
+|------|-----------|----------|------|
+| `sm` | `--field-height-sm` | `h-field-sm` | text-body |
+| `md` | `--field-height-md` | `h-field-md` | text-body |
+| `lg` | `--field-height-lg` | `h-field-lg` | text-body-lg |
+
+高度使用 `--field-height-*` semantic token（rem 單位），與 Button 共用同一組 token，同 size 的 Field 和 Button 並排時高度一致。
+
+---
+
+## Focus 行為
+
+`<input>` 元素在點擊和鍵盤 Tab 時都觸發 `:focus-visible`（瀏覽器規範：文字輸入永遠 focus-visible），CSS 無法區分。
+
+統一使用 `border-primary`（1px），不加 ring、不加粗。
+
+---
+
+## 點擊與游標原則
+
+### 點擊穿透
+
+Field 內部所有不會觸發獨立 action 的元素必須 `pointer-events-none`，讓點擊穿透到底層的 input/select，確保使用者點擊 Field 內任何位置都能 focus/activate。
+
+穿透（`pointer-events-none`）：startIcon、ChevronDown 下拉箭頭、tag 文字區域。
+不穿透：endAction（clear、toggle password）、tag dismiss button——這些有自己的 action。
+
+### 游標指引
+
+可點擊的元素必須有明確的 cursor 變化：
+- endAction、dismiss button → `cursor-pointer`
+- input / select → `cursor-text` / `cursor-pointer`（原生行為）
+- disabled → `cursor-not-allowed`
+
+## Icon 色彩原則
+
+跨元件統一規則（詳見 `item-anatomy.spec.md`）：**icon 代表內容/類別 → 與 label 同色；icon 純指示方向 → fg-muted（neutral-7）。**
+
+Field 內的具體套用：
+
+- **startIcon**（Search、Calendar）：`fg-muted`——指示 field 用途，不是 value
+- **ChevronDown 下拉箭頭**：`fg-muted`——指示可下拉
+- **代表 value 的 icon**（如狀態 icon）：**foreground**——icon 本身就是 value 的一部分
+- **disabled 時**：所有 icon 統一 `fg-disabled`
+
+## startIcon
+
+左側靜態 icon，輔助使用者理解 input 的用途（如 Search icon）。屬於 input 的視覺提示，不屬於 value。
+
+- 顏色 `fg-muted`（disabled 時 `fg-disabled`）
+- `aria-hidden`——純裝飾
+- 命名與 Button 的 `startIcon` 一致
+
+## 下拉箭頭（Select / Combobox）與類型身份 indicator
+
+Select / Combobox 的 ChevronDown、DatePicker 的 Calendar、TimePicker 的 Clock = **類型身份 indicator**(「這是什麼欄位」)。**edit 顯示(可互動)/ readonly 不顯示 / disabled 顯示(灰示)**(2026-06-26 user 拍板;readonly = 純值顯示、不可開下拉 → 箭頭會誤導故不顯;disabled 保留對齊原生 `<select disabled>` 灰示箭頭 + MUI #19833 / Carbon read-only「keep icon signifiers de-emphasized」/ Accordion M24 precedent):
+
+- edit:`fg-muted`;**readonly:不顯示 indicator**;**disabled:`fg-disabled`**(對齊上方 Icon 色彩原則)
+- 不可互動(`pointer-events-none`)——下拉由 select 元素本身觸發
+- **Cell(naked variant)例外**:indicator 依 `showDisplayEndIcon`(= cell 的 isEditable)——非可編欄不顯(2026-05-10 cell canonical「indicator = editable affordance」);**可編欄的 disabled cell 顯示 + fg-disabled**(同表單邏輯)
+- locked(readonly/disabled)wrapper 並設 `aria-disabled`(disabled 時)——styled-disabled 非原生元素需明告 AT inactive,亦使 axe 正確套用 WCAG 1.4.3 inactive-UI 豁免
+- clearable 有值時：clear X 在左，ChevronDown 在右
+- **右側元素(clear / chevron / calendar / clock)右緣水平內距 = `--field-px`(12px,SSOT `tokens/uiSize/uiSize.css`),edit / readonly / disabled / display 全 mode 一致**(跟 Input 一致)。**tag 模式特例**:左側 `tagPadding` 用對稱 px-calc(≈8px)貼齊 tags、會吃掉右緣,故 tag 容器(含 readonly/disabled)**必 re-assert `paddingRight: var(--field-px)`** 對齊 edit;漏接 = chevron 右緣偏移 bug(2026-06-27 修 Select:354 / Combobox ReadonlyMultiSelect)
+- **多行(Combobox tag wrap)垂直對齊**:tags 換行、容器動態變高時,右側 chevron **鎖第一行 tag 中線**(非整體置中)——容器 `items-start` + `ItemSuffix self-start` + `style={{ height: tagHeight }}`(sm 20 / md+lg 24)。對齊 item-anatomy「suffix 永遠 `h-[1lh]` 對齊第一行」canonical;edit / readonly / disabled 全 mode 一致(2026-06-27 補 readonly/disabled wrap 漏接)
+
+## Select 顯示模式
+
+Select 支援兩種顯示模式（`display` prop）：
+
+| 模式 | edit | readonly / disabled | 適用場景 |
+|------|------|---------------------|---------|
+| `plain`(預設) | 原生 select 純文字 + ChevronDown | 跟 Input 一致（純文字 + 標準 padding） | 狀態、類別等文字選項 |
+| `tag` | Tag + 隱藏 select overlay + ChevronDown | Tag + tagPadding | 需要視覺標記的選項（顏色標籤等） |
+
+`plain` 模式可搭配 `startIcon`(代表 value 的圖示,如狀態 icon;2026-05-01 由 `text` 改名 `plain`,rationale 見 `select.spec.md`)。
+
+`tag` 模式的 edit 用 hidden select overlay(跟 Combobox 同模式),Tag 用 `pointer-events-none`,點擊穿透到 select。右側元素右緣 = `--field-px`(見上方「右側元素」canonical;tag 模式 readonly/disabled 必 re-assert)。
+
+tagPadding 只在有 Tag 時才套用。Placeholder/空值狀態使用 fieldWrapper 的標準 `--field-px`(`px-[var(--field-px)]`)padding，確保文字與邊框有足夠間距。
+
+---
+
+## endAction（Inline Action）
+
+右側可互動元素，用於操作動作（清除內容、顯示密碼等）。
+
+使用宣告式 API：
+
+```tsx
+<Input endAction={{ icon: X, label: '清除', onClick: handleClear }} />
+```
+
+Field 內部用 `<ItemInlineAction>`(`patterns/element-anatomy/item-anatomy.tsx` 共用元件)渲染 — 跟 Sidebar / TreeView / DropdownMenu 的 inline action **完全同一套** canonical 實作,不再有「每個 host 自己複製 18 行 button JSX」的漂移。
+
+- 共用規則見 `patterns/element-anatomy/item-anatomy.spec.md`「Inline Action 設計規格」節
+- Helper 規格與 API 見 `item-anatomy.spec.md` 的「Inline action 共用元件」節
+- Field host 必須傳 `size={size}` 給 `<ItemInlineAction>`(field 不在 `RowSizeContext` 內,需明確覆寫)
+
+Icon 色彩遵循 Inline Action 統一規則:預設 `fg-muted`,hover 時 `foreground`。
+
+- disabled / readonly 模式不渲染 endAction
+- 條件渲染即可——消失後不佔位,input 自然擴展
+- 下拉箭頭不屬於 endAction,屬於 Select / Combobox
+
+**特例:Tag dismiss**——Tag 的 dismiss button 需要 chromatic hover bg(跟 tag 的 solid variant 色相一致),不是中性的 neutral-hover。2026-05-01 起改消費 `ItemInlineActionButton` + `hoverBgClassName` override prop 套色相 token(消除原自刻 `<button>` 繞 DS infra 的 tech debt),詳見 `tag.tsx` TagDismiss 註解。
+
+**Escape hatch**(10% case config 表達不出時):每 Field host 提供 `endSlot?: React.ReactNode`,規則 SSOT 見 `patterns/element-anatomy/inline-action.spec.md`「Escape hatch」節。
+
+---
+
+## Display — 格式化顯示(mode="display")
+
+每個 Field 元件以 `mode="display"` 渲染分支把 raw value 格式化為純展示輸出(已取代過往的 `XxxDisplay` 子元件;唯一現存 cross-component display primitive 是 PeoplePicker 的 `PersonDisplay`)。
+
+Display 的消費者:
+- **DataTable cell**:cell-registry 根據 `meta.type` 選對應 Field 元件並傳 `mode="display"`(disabled cell 傳 `"disabled"`)
+- **Field readonly 模式**:內部使用相同的格式化邏輯
+
+### null / undefined 值
+
+Display 模式統一顯示 em dash `—`，顏色 `text-fg-muted`。edit 模式顯示空白。
+
+此規則適用於所有 Field 類型，boolean 例外（顯示 unchecked 狀態）。
+
+### DataTable 整合
+
+DataTable 根據 column 的 `meta.type` 自動選擇 Field 元件(以 `mode="display"` 渲染):
+
+```tsx
+// 自動渲染——不需要手寫 cell
+col.accessor('price', {
+  header: 'Price',
+  meta: { type: 'currency', prefix: '$' },
+})
+
+// 客製化——有自訂 cell 時完全跳過 type → Display
+col.accessor('status', {
+  header: 'Status',
+  cell: (info) => <MyCustomBadge status={info.getValue()} />,
+})
+```
+
+兩者可在同一張 table 混用。
+
+---
+
+## 共享 contract(2026-05-12 Stream C — Selected renderer / Placeholder vocabulary / Cell surface)
+
+**(a) Selected value renderer**:rich display(avatar+name/icon+label)元件**必**提供 consumer renderer slot,**display/readonly/disabled/edit** 4 mode 共享同一 renderer(禁 edit-only)。`Select.selectedItemRenderer` / `Combobox.tagRenderer`(edit 已接;display path unify deferred 下 cycle)/ PeoplePicker 走 `PersonDisplay`+`MultiPersonDisplay`+`Combobox.tagRenderer`。對齊 MUI Autocomplete `renderValue` / Ant Select `tagRender`+`labelRender`+`optionRender` / MUI DataGrid `renderCell`+`renderEditCell` 共享 params。 <!-- @benchmark-unverified -->
+
+**(b) Placeholder vocabulary**(3 props 對 3 UI state,**不可混用**):
+- `placeholder` — trigger empty(沒選值,例「請選擇人員」)— Ant/Polaris/Carbon canonical
+- `searchPlaceholder` — search input hint(例「搜尋人員…」)— Ant `searchPlaceholder`
+- `emptyText`/`noResultsText` — filtered menu 無結果(例「沒有符合的人員」)— Ant `notFoundContent` / Material X `localeText.noResultsOverlayLabel`
+
+**禁**:wrapper 把 `emptyText`(search-empty)silent forward 成 `emptyPlaceholder`(trigger-empty);**Combobox `emptyPlaceholder` deprecated**,保留 1 cycle fallback,future `placeholder` 唯一 trigger source。Hook `check_field_controls_contracts.sh` (contract b) 機械強制。
+
+**(c) Cell surface metrics**:Field family 在 cell 內**禁** hardcode padding(`tagAreaPaddingLeftPx={isEmpty ? undefined : 8}` 反 pattern)。改 **`FieldSurface` context**(`'form' | 'toolbar' | 'table-cell'`):`useFieldSurface()` 取值,`<FieldSurfaceProvider surface="table-cell">` 自動套於 `cell-registry.resolveCellComponent`。Consumer 用 `surface === 'table-cell'` 顯式 query(取代 `variant === 'naked'` heuristic)。**risk mitigation**:`avatar.left = cell.left + computed(--table-cell-px)`,禁再加 magic 8px(double-count)。**Token scope**:`--table-cell-px/py` 是 DataTable-scoped metric(CSS 定義在 `data-table.css`,Field naked variant 是 DataTable cell substrate sub-component 故 cross-path reference 不算真 cross-component),per 2026-05-13 codex Q2 verdict + AG Grid `cellHorizontalPadding`(grid theme param)/ MUI X `cellClassName`(per-cell)/ Carbon spacing scale primitive(不升 cell padding 全域 token)idiom — **不**升 `tokens/layoutSpace/` canonical。對齊 AG Grid cellRendererSelector / Material X DataGrid 共享 params / Notion property type registry。Hook `check_field_controls_contracts.sh` (contract c) 機械強制。 <!-- @benchmark-unverified -->
+
+**(d) Default variant display = zero chrome SSOT**(2026-05-13 user 拍板 Path Ⅰ + codex V2 verdict):default `mode='display'` **必** zero chrome。Display 純展示語意,真要包 chrome 走 `readonly` 或 `showDisplayEndIcon=true` opt-in。**Impl**:`field-wrapper.tsx` + `textarea.tsx` compoundVariants `mode:'display'+variant:'default'` 加 `!px-0 !py-0`。對齊 Carbon read-only / Stripe display / Notion property / Polaris readonly。Hook `check_field_controls_contracts.sh` (contract d) propose。 <!-- @benchmark-unverified -->
+
+**(e) Display typography canonical**(2026-05-14 user I2 + codex M31 verdict):Field family display path **必** consume `fieldWrapperStyles` size variants typography token — `sm/md → text-body`(14px line-height 1.5)/ `lg → text-body-lg`(16px)。**禁**:LinkInput / Select / Combobox 非 D-path 的 bare-span 直接 render 無 font-size class(瀏覽器 default 字體);**必**包 `text-body` (sm/md) / `text-body-lg` (lg) class。對齊跨 Field family display 視覺尺寸統一(user 抓 LinkInput display 字體跟其他 Field 不一致 = SSOT 違反 漏接 typography token)。**Impl**:LinkInput / Select / Combobox / DatePicker / TimePicker non-D-path bare-span 加 size-aware text class。world-class cite:MUI X DataGrid `Typography` consistent / Atlassian @atlaskit/textfield size-prop typography token / Polaris TextField typographyToken size-aware。 <!-- @benchmark-unverified -->
+
+---
+
+## 邊界案例(家族共用 pointer)
+
+- **極長輸入溢出**:由各元件 spec own — Input 超寬走原生水平捲動(`input.spec.md`「邊界(內容超寬)」)、Textarea 內容超出時 native 內部捲動 / display 態隨內容增高(`textarea.spec.md`「極長文字」)。
+- **常見誤解 — disabled 時 label 該隱藏?**:不隱藏 — label 保留但變灰(`FieldLabel` disabled 灰化、required 星號同步 `text-fg-disabled`,SSOT `Field/field.spec.md`);停用原因由外部 Tooltip / help text 承擔(見「disabled 的停用原因」)。
+
+## 表單驗證原則
+
+詳見 `Field/form-validation.spec.md`。
+
+## 禁止事項
+
+- ❌ 不在 disabled input 內放 info icon——停用原因由外部 Tooltip 或 Form help text 承擔
+- ❌ 不在 input 尾部放 error 狀態 icon——邊框顏色已傳達 error
+- ❌ endAction 不可傳入 ReactNode——使用 InlineActionConfig 宣告式 API
+- ❌ endAction 的 inline action 不可省略 `aria-label`（即 `label` 欄位）
+- ❌ Display 的 null 值不可顯示空白——統一使用 `—`（em dash）+ `text-fg-muted`
+- ❌ Field 的 readonly 模式不可用於 DataTable cell——readonly 有底色和 wrapper 開銷，table cell 用 Display 元件
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `checkbox.spec.md`
+- `circular-progress.spec.md`
+- `combobox.spec.md`
+- `date-picker.spec.md`
+- `element-anatomy.spec.md`
+- `field-control-group.spec.md`
+- `field.spec.md`
+- `form-validation.spec.md`
+- `input.spec.md`
+- `item-anatomy.spec.md`
+- `link-input.spec.md`
+- `number-input.spec.md`
+- `people-picker.spec.md`
+- `rating.spec.md`
+- `segmented-control.spec.md`
+- `select.spec.md`
+- `slider.spec.md`
+- `switch.spec.md`
+- `textarea.spec.md`
+- `time-picker.spec.md`

package/src/components/Field/field-types.ts

@@ -9,7 +9,7 @@
 //   disabled — input chrome + disabled state(灰底,不可互動,語意「不適用」)
 //
 // `display` vs `readonly` 判別:
-//   - 該位置語意上是「純展示資料」(如 DataTable cell read mode / NameCard meta) → `display`
+//   - 該位置語意上是「純展示資料」(如 DataTable cell read mode / ProfileCard meta) → `display`
 //   - 該位置是「表單欄位但目前不可改」(如 form 鎖部分欄位) → `readonly`
 //
 // World-class refs(M22 verified):

package/src/components/Field/field-wrapper.tsx

@@ -8,7 +8,7 @@ import { cva } from 'class-variance-authority'
 //   edit     — bg-surface, border, hover/focus 回饋(可編輯 input)
 //   display  — 純展示(無 input chrome、無 affordance);語意「read-only 內容,展示給人看」。
 //              對齊 Carbon read-only / PatternFly inline-edit hidden-input。
-//   readonly — bg-disabled(neutral-2), 無邊框, 文字正常色(input chrome 但鎖定)
+//   readonly — bg-readonly(neutral-2), 無邊框, 文字正常色(input chrome 但鎖定;token 獨立於 disabled)
 //   disabled — bg-disabled(neutral-2), 無邊框, 文字灰化
 //
 // 2 種視覺外殼(variant):
@@ -57,9 +57,9 @@ export const fieldWrapperStyles = cva(
         naked: '',
       },
       size: {
-        sm: 'text-body h-field-sm px-3 gap-2',
-        md: 'text-body h-field-md px-3 gap-2',
-        lg: 'text-body-lg h-field-lg px-3 gap-2',
+        sm: 'text-body h-field-sm px-[var(--field-px)] gap-2',
+        md: 'text-body h-field-md px-[var(--field-px)] gap-2',
+        lg: 'text-body-lg h-field-lg px-[var(--field-px)] gap-2',
       },
     },
     // mode x variant 交叉:visual chrome 由 compoundVariants 決定
@@ -98,7 +98,7 @@ export const fieldWrapperStyles = cva(
         mode: 'display',
         variant: 'default',
         // 2026-05-13 Q3 Path Ⅰ(user 拍板 Path Ⅰ 全 zero chrome + codex V2 verdict + field-controls.spec.md (d)):
-        // default display = zero chrome — !px-0 !py-0 override size token 的 px-3,跟 Select / Combobox
+        // default display = zero chrome — !px-0 !py-0 override size token 的 px-[var(--field-px)],跟 Select / Combobox
         // / DatePicker / TimePicker / LinkInput non-D-path bare-span idiom 一致(Carbon read-only / Stripe
         // display / Notion property / Polaris readonly TextField 全 zero chrome)。
         className: 'bg-transparent border border-transparent !px-0 !py-0',
@@ -106,7 +106,7 @@ export const fieldWrapperStyles = cva(
       {
         mode: 'readonly',
         variant: 'default',
-        className: 'bg-disabled border border-transparent',
+        className: 'bg-readonly border border-transparent',
       },
       {
         // 2026-05-13 R3.5(per codex Q3 verdict + user 拍「想盡辦法 auto-handle prereq」):