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

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

@@ -58,6 +58,20 @@ components/
 
 ---
 
+## Field 框架地圖(兩軸 + InlineEdit 疊上層)— SSOT(2026-07-09 user 拍板收斂)
+
+Field 家族 = **一個 `fieldWrapperStyles` cva + 兩條正交軸**;`InlineEdit` 是**疊在其上的組合 primitive**,不屬於任一軸。此段為「框架為何長這樣」的單一住所。
+
+**軸一 `mode`(4)× 軸二 `variant`(2)**:`variant` 只有 `default`(公開,完整 chrome)與 `naked`(`@internal`,cell-as-input:edit×naked 自畫 border-based state machine,display/readonly/disabled×naked 用 transparent border 由 host cell 供視覺邊框;只 DataTable `cell-registry.tsx` 消費)。`bare`(透明外殼)**2026-07-09 退役**——零真實消費者 + 假理由(toolbar 小輸入用 `default`+`autoWidth`,cell 用 `naked`);SSOT `field-types.ts` `FieldVariant`。有效組合:default × {edit/display/readonly/disabled} 全用於表單/詳情;naked × {edit/display/disabled} 用於 DataTable 格;`naked+readonly` 目前無 live consumer(格子非 readonly 模式),保留 compound 為軸對稱。readonly 2026-07-09 補鍵盤 focus ring(WCAG 2.4.7,見「Focus 行為」)。**型別層已拆 public/internal union(2026-07-14 API 策展 E,user 拍板「全部收窄」)**:公開 `FieldVariant = 'default'`;`naked` 收進 `FieldVariantInternal`(`@internal`),cell-registry 經 `WithFieldVariantInternal` 型別通道消費(純型別 widen、零 runtime),PeoplePicker wrapper 同通道 forward 給 Select / Combobox。
+
+**InlineEdit ≠ mode ≠ variant**:它是 **read↔edit 二態切換**——靜止 = 純文字(文字 + 隱形 Pressable),點擊/Enter 才生一個 **Field 控件**(edit view,預設 `<Input>`,可 `renderEdit` 換 Textarea/Select)。它**消費** Field edit mode 當「edit 那一半」,站在 mode 軸**之上**(比喻:Field edit = 燈泡,InlineEdit = 開關)。世界級對照 [Atlassian inline-edit](https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx)。
+
+**`naked` vs `InlineEdit`(不同層級,非冗餘)**:`naked` = 視覺外殼變體(chrome 層),靜止態**仍是控件**(裸 input,直接可編輯),邊框由 host cell 管,對應 in-cell 即時編輯(spreadsheet / grid 慣例);`InlineEdit` = 互動組合(behavior 層),靜止態**不是控件**(純文字),自帶 read chrome,對應 click-to-edit([Atlassian inline-edit](https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx))。naked 做不到「靜止純文字、點了才變輸入框」;InlineEdit 塞不進格子當永遠在線編輯器 → 各自獨立。
+
+**InlineEdit 多行 / padding / 零位移契約**:read view 文字可換行(`w-full min-w-0` 無 nowrap)。**多行(`multiline` prop,2026-07-09 L2)**:edit view **自動**用 `<Textarea>`(Enter=換行、Cmd/Ctrl+Enter 或 blur 提交),read view `whitespace-pre-wrap` 保留換行,**不需手傳 renderEdit**(對齊 DataTable 可換行格 `autoRowHeight`+`<Textarea variant="naked">`+`line-clamp`,`cell-registry.tsx`)。垂直 padding:**單行** read 用 `min-h-[--field-height-{size}]`+flex 置中、無 `py`(與 Textarea `py-2` 不同);**多行** read 用 `items-start py-1.5`(對齊 Textarea 多行閱讀語意)。進 edit **零位移**:read 恆帶透明 border(預留 1px border-box)+ `px-[--field-px]`(= edit Input 同值)→ 左右/邊框零跳;垂直單行時 read `min-h` = edit height 零跳(多行須配 Textarea 否則垂直不齊)。
+
+---
+
 ## Mode — 表單三態 (display 見下方 Display 段)
 
 下表涵蓋 Form-context 三態(edit / readonly / disabled);完整 `FieldMode` 為四值(`'edit' | 'display' | 'readonly' | 'disabled'`),`display` 模式於下方 `## Display` 段記載。
@@ -139,7 +153,7 @@ Error 是 boolean prop，獨立於 mode。只在 `edit` 模式下有視覺效果
 - Error 訊息在 Form 層級：help text 顯示在 input 下方
 - Field 不在尾部放狀態 icon（如 ⚠️）——邊框顏色已經傳達了 error 狀態
 
-Form wrapper 可透過 context 注入 `error` prop，消費者不需要在每個 Field 上手動傳。
+Field wrapper 透過 context 注入的 key 是 `invalid`(**非 `error`**;field.tsx:122/211);各控件以 `useResolvedFieldInvalid` 合併自身 `error` prop 與 context `invalid`,消費者不需在每個控件手動傳。（`error` 另為 `fieldWrapperStyles` 內部 cva 軸名 + 各控件公開 boolean prop;Field 容器層 / context 一律用 `invalid`。）
 
 ---
 
@@ -183,11 +197,30 @@ Form wrapper 可透過 context 注入 `error` prop，消費者不需要在每個
 
 ---
 
+## 寬度軸(width: fill / hug)— 正交軸(2026-07-08 user 拍板)
+
+Field 家族 wrapper 的寬度軸,與 mode / variant / size / error 全部正交:
+
+| width | 行為 | 何時用 |
+|-------|------|--------|
+| `fill`(default)| `w-full` 填滿容器 — 原行為,零回歸 | form 表單直欄(欄位左緣對齊)、DataTable cell |
+| `hug` | `w-fit max-w-full` 依內容收縮 | detail pane inline metadata(狀態/優先級/負責人 點擊即編輯)、toolbar 內 field |
+
+**定義(user verbatim)**:hug 寬 = value 寬 + 其中各元素寬 + 彼此間距 + field 內部 padding —— **框線、互動、樣式全部不變,只有寬度變**(就是一般 field 把寬度改 hug)。`max-w-full` 保證窄容器不溢出(`min-w-0` + truncate 照常)。
+
+- 鋪線範圍:`fieldWrapperStyles` cva 軸(SSOT)+ Select / Combobox / DatePicker / PeoplePicker 轉發 `width?: FieldWidth`(型別 `Field/field-types.ts`)
+- **何時不用**:form 直欄(fill 對齊)、DataTable cell(naked 已 `!h-full` 滿格,cell 寬由 column 管)
+- Benchmark(M22):shadcn v4 SelectTrigger 預設 `w-fit`(https://raw.githubusercontent.com/shadcn-ui/ui/main/apps/v4/registry/new-york-v4/ui/select.tsx)/ Radix Select Trigger intrinsic sizing(https://www.radix-ui.com/primitives/docs/components/select)
+
+---
+
 ## Focus 行為
 
 `<input>` 元素在點擊和鍵盤 Tab 時都觸發 `:focus-visible`（瀏覽器規範：文字輸入永遠 focus-visible），CSS 無法區分。
 
-統一使用 `border-primary`（1px），不加 ring、不加粗。
+**可編輯文字輸入(edit / naked mode 的 input / textarea)**:統一 `border-primary`（1px），不加 ring、不加粗。
+
+**readonly(可聚焦但不可編輯的 input,2026-07-09 補 — 消解框架地圖 cross-ref)**:用 **ring idiom**(`[&:has(:focus-visible)]:ring-2 ring-ring ring-offset-1`;native text input 的 :focus-visible 在滑鼠點擊時**亦 match** — 對齊本段開頭「文字輸入永遠 focus-visible、CSS 無法區分點擊與 Tab」,勿宣稱僅鍵盤),**非** border-primary —— readonly 邊框 transparent 無可染,且 ring 語義=「可聚焦但非文字輸入」(對齊 Button / Tab / Checkbox);滿足 WCAG 2.4.7(readonly 有值渲染可聚焦 native input 需 focus 指示)。詳 `field-wrapper.tsx` readonly compound JSDoc。
 
 ---
 
@@ -232,7 +265,7 @@ Select / Combobox 的 ChevronDown、DatePicker 的 Calendar、TimePicker 的 Clo
 
 - 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**(同表單邏輯)
+- **Cell(naked variant)**:**display 態零恆顯 indicator(2026-07-08 user 拍板 A 案,推翻 2026-05-10「indicator = editable affordance」)** —— editable affordance 統一 = hover outline(field.spec.md L4)。Benchmark 6/6 product-table 域(Ant editable-cells / MUI X singleSelect / AG Grid / Atlaskit inline-edit(v2.0.0 移除 hover-pencil 後 9 版未回歸)/ Notion / Airtable)display 態皆純值零 icon;恆顯派僅 Google Sheets Chip/Arrow(spreadsheet 域可選檔位)。`showDisplayEndIcon` prop 保留為 opt-in 逃生門(spreadsheet-flavored 消費端);cell-registry 6 個 picker 站不再傳、url 站傳 `isEditable === true`(LinkInput 例外 = wrapper-only 無 icon,取 display↔edit 像素對齊)。edit 態 indicator 照舊(本節上方 form 規則);opt-in 時 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)
@@ -249,6 +282,8 @@ Select 支援兩種顯示模式（`display` prop）：
 
 `plain` 模式可搭配 `startIcon`(代表 value 的圖示,如狀態 icon;2026-05-01 由 `text` 改名 `plain`,rationale 見 `select.spec.md`)。
 
+`selectedItemRenderer` 設定時優先於 plain / tag 預設呈現,且 **4 mode(edit/display/readonly/disabled)共享**(共享 contract (a),見下方)— display 態渲染 renderer 輸出(值內容),無 chrome 無 chevron。
+
 `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，確保文字與邊框有足夠間距。
@@ -291,11 +326,30 @@ Display 的消費者:
 - **DataTable cell**:cell-registry 根據 `meta.type` 選對應 Field 元件並傳 `mode="display"`(disabled cell 傳 `"disabled"`)
 - **Field readonly 模式**:內部使用相同的格式化邏輯
 
-### null / undefined 值
+### null / undefined 值(2026-07-08 user 拍板 — 半形 hyphen + editable × surface 分流)
+
+> **user verbatim**:「table cell 不可編輯的空值,單獨不可編輯的 display 的空值,單獨的 readonly 的空值都用"-";單獨可以編輯的 edit 輸入框的空值則是 placeholder;table cell 內可編輯的 display 的空值就是為空」+「我從頭到尾哪裡有說要用全形的」。
+
+空值符號 = **半形 hyphen `-`(U+002D)**,**非**全形 em dash `—`(U+2014)。分流看 **surface × 是否可編輯 × mode**(SSOT 機械層 = `field-context.ts` `useFieldEmptyDisplay()` + `EMPTY_DISPLAY` 常數 `field-wrapper.tsx`;全 Field family display/readonly/disabled 空值渲染必經此 hook,**禁**直接引 `EMPTY_DISPLAY` 常數):
+
+| 情境 | 判準 | 空值顯示 | 依據 |
+|---|---|---|---|
+| 不可編輯 — standalone display / readonly | mode ∈ {display, readonly} 且非可編輯 table cell | **半形 `-` + `text-foreground`** | 唯讀資料「此欄無值」明示;Ant ProTable `columnEmptyText` 預設 `'-'`(https://github.com/ant-design/pro-components/blob/master/src/table/Table.tsx)|
+| 不可編輯 — table cell(readonly cell)| `surface==='table-cell'` 且 `isEditable===false` | **半形 `-`** | 同上;非可編欄位視同唯讀資料 |
+| **可編輯** — table cell display 靜止態 | `surface==='table-cell'` 且 `isEditable===true` 且 mode='display' | **全空白 `''`** | grid 域壓倒性共識(MUI X `valueToRender?.toString()` null 短路 / AG Grid `_toString(null)`→不設 textContent / Ant core rc-table 裸值 / Notion / Airtable);表格密集時「-」海 = 視覺噪音。空 editable cell 的 affordance = hover outline(field.spec.md L4),非佔位符 |
+| **可編輯** — form / panel edit 輸入框 | mode='edit' 且非 table cell | **native placeholder** | 標準表單輸入提示;「hover 才顯 placeholder」十路查證零家採用,**禁** |
+| **可編輯** — table cell edit / focus | `surface==='table-cell'` 且 mode='edit' | **全空白**(DataTable cell 不接 placeholder)| 對齊 Notion / Airtable cell 編輯裸輸入 |
+
+收斂式:`surface==='table-cell' && isEditable ? '' : '-'`(可編輯 form edit 走 native placeholder,不經此 hook)。`isEditable` 由 DataTable cell registry 經 `FieldSurfaceEditableProvider` boolean context 注入(standalone / form 無此 context → 預設 false → `-`)。
+
+**readonly native input 兩派統一**(2026-07-08):Input / Textarea 的 readonly **空值** 改走 display-span 顯 `-`(原走 native `<input readOnly>` 吐 native placeholder / 空白);readonly **有值** 仍走 native input 保留選取/複製語意。NumberInput 早已 `resolvedMode !== 'edit'` 統一走 span,無需改。「有值」判定(2026-07-14 補註,dual-model consensus;不改空值顯 `-` 規則本身):uncontrolled(只傳 `defaultValue`)同樣算有值 —— 機械層 = `useControllable` 內部 resolved value(defaultValue 初始 + 打字寫回,native element 由 `value={resolved}` 內部驅動)+ form.reset() bridge(HTML reset 不發 input event → uncontrolled 掛 form `reset` listener 把 resolved 歸位 defaultValue),切 display / readonly(native element unmount/remount)後判定與 DOM 真值一致、不顯 stale 值;controlled 純 passthrough 行為不變。
 
-Display 模式統一顯示 em dash `—`，顏色 `text-fg-muted`。edit 模式顯示空白。
+**空值符號顏色**(2026-07-09 user 拍板 verbatim「「-」代表的是不可編輯只拿來供檢視的值所以應該跟readonly 的value同樣顏色吧」):不可編輯「-」= `text-foreground`(同 readonly value 色,非 placeholder 提示的裝飾語意);disabled → `text-fg-disabled`(M24)。SSOT helper = `field-context.ts` `fieldEmptyColorClass(resolvedMode)`,全 Field family display/readonly/disabled 空值 span 消費(禁散寫 `text-fg-muted`)。
 
-此規則適用於所有 Field 類型，boolean 例外（顯示 unchecked 狀態）。
+**例外表**(唯一去處,禁散落各元件 spec):
+- **boolean** → 顯示 unchecked 狀態(非空白非 dash)
+- **disabled** → 同該情境上文字(`-` 或空白)+ `text-fg-disabled`(M24:disabled 顯著性 > muted)
+- **Select display 傳 `placeholder`** → 顯 placeholder 而非 dash/空白(`select.tsx` `emptyText = placeholder ?? emptyDisplay`,2026-07-08 codify — 原為 spec 未載明的 code 行為)
 
 ### DataTable 整合
 
@@ -321,7 +375,7 @@ col.accessor('status', {
 
 ## 共享 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 -->
+**(a) Selected value renderer**:rich display(avatar+name/icon+label)元件**必**提供 consumer renderer slot,**display/readonly/disabled/edit** 4 mode 共享同一 renderer(禁 edit-only)。`Select.selectedItemRenderer`(4 mode 已全接 — 2026-07-08 A 案回歸修正,display/readonly/disabled 的 ReadonlyDisplay 消費 renderer 輸出;renderer 輸出屬「值內容」,display 態照常渲染,與 affordance 分層見 `field.spec.md` L6)/ `Combobox.tagRenderer`(edit 已接;display path 走 ComboboxTagStack 預設 Tag,consumer tagRenderer unify 仍 deferred,見 `combobox.tsx` 檔頭 `@renderer-symmetry-allow`;現行唯一 tagRenderer consumer = PeoplePicker,其 display 走 MultiPersonDisplay 不經此 path,無實際丟失)/ 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
@@ -353,7 +407,7 @@ col.accessor('status', {
 - ❌ 不在 input 尾部放 error 狀態 icon——邊框顏色已傳達 error
 - ❌ endAction 不可傳入 ReactNode——使用 InlineActionConfig 宣告式 API
 - ❌ endAction 的 inline action 不可省略 `aria-label`（即 `label` 欄位）
-- ❌ Display 的 null 值不可顯示空白——統一使用 `—`（em dash）+ `text-fg-muted`
+- ❌ 不可編輯 display / readonly 空值用全形 em dash `—` 或 `text-fg-muted`——半形 `-` + `text-foreground`(「-」是供檢視的值,同 readonly value 色;disabled → fg-disabled);可編輯 table cell display 空值為空白(見「null / undefined 值」分流表)
 - ❌ Field 的 readonly 模式不可用於 DataTable cell——readonly 有底色和 wrapper 開銷，table cell 用 Display 元件
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)

package/src/components/Field/field-edit-keys.ts

@@ -0,0 +1,66 @@
+// @internal — DS-internal 單元(edit-in-place 鍵盤結算 SSOT);consumer 用 InlineEdit / DataTable,不直用。
+// ── 消費的 SSOT ──
+// (本檔即是被消費的 SSOT;不 import 其他 canonical)
+//
+// ── 為什麼存在 ──
+// 「就地編輯(edit-in-place)」的鍵盤結算契約 —— Enter=commit / Esc=cancel + **中文 IME 組字 guard** ——
+// 原本在兩處各寫一份、且**已分歧**:
+//   - DataTable `cell-registry.tsx` makeKeyHandler:有 IME guard(2026-07-05 D4 fix)
+//   - InlineEdit `inline-edit.tsx`:**無 IME guard** → 中文使用者按 Enter 確認選字時,會把半截組字
+//     提交並退出 edit(Esc 則丟棄整個 draft)= latent bug。
+// 2026-07-09 edit-in-place SSOT 研究(6-agent + 世界級)結論:**不抽大的共用狀態機**(兩 host 的 draft
+// 擁有權 / state locus / focus model 根本不同,強抽違 M21 + 破壞表格虛擬捲動效能),**但抽這一片**——
+// 唯一在兩處逐字重複、且現在分歧、且不碰 draft/state/focus 的純鍵盤結算邏輯。抽出後 InlineEdit 順手
+// 得到 IME guard(修 bug)。對齊世界級「controls + 型別 registry 共用,orchestration 各自」split。
+//
+// **不含**:blur=commit(各 host 的 blur 語意不同)、finalizedRef 單次結算 guard(InlineEdit 專屬,
+// 防 blur-after-Enter 雙 commit)、draft 管理(host-specific)。這些刻意留在各 host。
+//
+// ── 新增 edit-in-place host 的規矩(2026-07-10)──
+// 之後任何新的「就地編輯」host(第 3 個以上),**Enter/Esc/Cmd·Ctrl+Enter/IME 組字結算一律消費本
+// helper**,禁再手刻 `isComposing || keyCode===229` guard 或 Enter/Esc dispatch —— 現有 3 host
+// (cell string / cell number / InlineEdit multiline)已全數收斂於此,手刻 = drift 回頭路(正是 2026-07
+// 之前 InlineEdit 漏 IME guard 的病根)。單行傳 `commitOnEnter` 預設;多行傳 `commitOnEnter:false`
+// (本 helper 內建 Cmd/Ctrl+Enter=commit)。此為文件層 SSOT 規矩,不另設 hook(host 少 + 避治理膨脹)。
+
+import type * as React from 'react'
+
+export interface EditSettleKeyOptions {
+  /** Enter(非組字中)→ 呼叫。已 preventDefault。 */
+  onCommit: (e: React.KeyboardEvent) => void
+  /** Escape(非組字中)→ 呼叫。已 preventDefault。 */
+  onCancel: (e: React.KeyboardEvent) => void
+  /**
+   * Enter 是否 = commit。預設 true。
+   * 多行(Textarea)場景設 false:plain Enter = 換行(不攔,交還 Textarea 預設),
+   * Cmd/Ctrl+Enter = commit(**本 handler 內建**,consumer 不需另接 capture handler),
+   * 其餘 commit 走 blur。
+   */
+  commitOnEnter?: boolean
+}
+
+/**
+ * edit-in-place 鍵盤結算 handler(SSOT)。IME 組字 guard 為第一道:中文/日文選字的 Enter 是
+ * 組字確認、Esc 是取消組字,非 commit/cancel 意圖 —— 無 guard 會誤送半截組字。`isComposing` 為主,
+ * `keyCode === 229` 補 Safari / 舊 Chrome(該分支不 emit isComposing)。
+ */
+export function makeEditSettleKeyHandler(opts: EditSettleKeyOptions) {
+  const commitOnEnter = opts.commitOnEnter ?? true
+  return (e: React.KeyboardEvent) => {
+    // IME 組字 guard(見檔頭)—— 對齊 cell-registry 既有寫法 + data-table nav handler。
+    if (e.nativeEvent.isComposing || (e.nativeEvent as { keyCode?: number }).keyCode === 229) return
+    if (e.key === 'Escape') {
+      e.preventDefault()
+      opts.onCancel(e)
+    } else if (e.key === 'Enter') {
+      // 單行(commitOnEnter):Enter = commit。
+      // 多行(commitOnEnter:false):plain Enter = 換行(不攔,交還 Textarea 預設),
+      //   Cmd/Ctrl+Enter = commit —— 此契約由本 SSOT 擁有,3 個 consumer
+      //   (cell string/number + InlineEdit multiline)不再各自手刻 capture handler。
+      if (commitOnEnter || e.metaKey || e.ctrlKey) {
+        e.preventDefault()
+        opts.onCommit(e)
+      }
+    }
+  }
+}

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

@@ -20,19 +20,68 @@ export type FieldMode = 'edit' | 'display' | 'readonly' | 'disabled'
 
 // ── Field Variant ────────────────────────────────────────────────────────────
 //
-// 視覺外殼(對齊主流 DS canonical M22 verified 2026-05-05):
-//   - Ant Design `Input variant`: 'outlined' | 'borderless' | 'filled' | 'underlined'
-//   - MUI `TextField variant`: 'outlined' | 'standard' | 'filled'
+// 視覺外殼(公開 1 + internal 1;2026-07-09 user 拍板退役 `bare`,2026-07-14 API 策展 E user 拍板
+// 「全部收窄」把 naked 從公開 union 拆出 — 見下方 note):
+//   default — 含 border + bg(一般 form input,= Ant outlined / MUI outlined)。公開 FieldVariant 唯一值
+//   naked   — @internal(FieldVariantInternal)。cell-as-input(host cell substrate)。edit×naked 自畫
+//             border-based state machine(rest → hover → focus-within:border-primary → error 紅框);
+//             display/readonly/disabled×naked 用 transparent border,由 host cell 提供視覺邊框。
+//             對齊 Airtable / Notion / Excel cell editing。唯一合法消費者 = DataTable cell-registry
+//             (field-controls.spec.md「軸二 variant」明文)— consumer 直傳 `<Input variant="naked">`
+//             會繞過 canonical chrome / focus,故公開型別排除
 //
-//   default — 含 border + bg(一般 form input,= Ant outlined / MUI outlined)
-//   bare    — 透明 variant,hover/focus 才 reveal inner border(VS Code/Figma toolbar inline editing idiom,
-//             ≈ Ant borderless,但保留 hover/focus reveal)
-//   naked   — 完全無 chrome / 無 focus ring on wrapper(cell-as-input — host cell 提供 border + focus visual)
-//             對齊 Airtable / Notion / Excel cell editing — cell 本身扮演 input frame,內無 wrapper
+// **`bare` 退役紀錄(2026-07-09)**:原「透明外殼、hover/focus 才顯 border」variant,2026-05-05 加入時
+//   宣稱用途 = toolbar inline editing(FileViewer zoom / config toolbar)。實測全 repo(DS + apps + stories)
+//   `variant="bare"` **零真實 JSX 消費者**:唯一出現處是一個 ❌ 反例 story + 過時註解(含錯誤宣稱 FileViewer
+//   縮放用 bare — 實為 `<Input size="sm" autoWidth>` default variant)。其目標場景已被 default(toolbar,
+//   對齊「邊框給互動元素、輸入框就該有邊框」原則)與 naked(cell-as-input)覆蓋 → 純冗餘,移除。
+//   ⚠️ 注意:被大量 import 的 `bareInputStyles` 常數(field-wrapper.tsx)是**內層 <input> 的重置樣式**
+//   (透明底 / 無 border / 繼承字體),與本 variant 同名但不同物,**保留不動**(8 個控件共用)。
 //
 // 透傳機制:Field 透過 FieldContext.variant 一次宣告,所有 child Field control 自動繼承。
 // per-control prop override 可覆寫 context。
-export type FieldVariant = 'default' | 'bare' | 'naked'
+//
+// Benchmark(M22 verified 2026-07-09):Ant `Input variant` 有 borderless(https://ant.design/components/input/)
+//   → 「無邊框輸入框」概念世界級合法;但 Material M3 只有 filled/outlined 無無邊框變體
+//   (https://m3.material.io/components/text-fields/guidelines),MUI standard(underline)已 deprecated。
+//   我們的取捨:無真實消費場景 → 不保留純預留 variant(對齊自家「消費既有、不憑空造」原則)。
+export type FieldVariant = 'default'
+
+/**
+ * @internal Substrate union — 公開 FieldVariant + `naked`(cell-as-input)。
+ * 2026-07-14 API 策展 E(user 拍板「全部收窄」):naked 從公開 union 拆出,型別層防 consumer
+ * `<Input variant="naked">` 繞過 canonical chrome / focus。內部實作(field-wrapper cva、各控件
+ * useResolvedFieldVariant 分支)吃本型別;唯一合法 naked 傳入點 = DataTable cell-registry
+ * (field-controls.spec.md「軸二 variant」明文)。
+ */
+export type FieldVariantInternal = FieldVariant | 'naked'
+
+/**
+ * @internal 型別層 naked 通道 — 把 Field control 的公開 `variant?: FieldVariant` widen 為
+ * FieldVariantInternal(純型別、零 runtime;元件 runtime 本就支援 naked)。消費者:DataTable
+ * cell-registry(naked 起點)+ PeoplePicker(wrapper forward 給 Select / Combobox,M30 全 surface
+ * forward)。保留原 call signature 與 statics(`Pick<C, keyof C>`),widen 方向與函式參數
+ * contravariance 相容,故單次 assertion 可過(非 `as unknown as` 雙跳,型別仍受檢)。
+ */
+export type WithFieldVariantInternal<C> = C extends (props: infer P) => infer R
+  ? ((props: Omit<P, 'variant'> & { variant?: FieldVariantInternal }) => R) & Pick<C, keyof C>
+  : never
+
+// ── Field Width ──────────────────────────────────────────────────────────────
+//
+// 寬度軸(2026-07-08 user 拍板,正交於 mode / variant / size — 只改寬度,chrome 與互動不變):
+//   fill — `w-full` 填滿容器(default;form 直欄對齊 / DataTable cell 滿格)
+//   hug  — `w-fit max-w-full` 依內容收縮:value 寬 + 各 slot 元素寬 + gap + field 內 padding
+//          (detail pane inline metadata / toolbar 內 field 場景)
+//
+// Benchmark(M22 verified):
+//   shadcn v4 SelectTrigger 預設 `w-fit`
+//     https://raw.githubusercontent.com/shadcn-ui/ui/main/apps/v4/registry/new-york-v4/ui/select.tsx
+//   Radix Select Trigger intrinsic sizing
+//     https://www.radix-ui.com/primitives/docs/components/select
+//
+// SSOT:fieldWrapperStyles `width` variant(field-wrapper.tsx)+ field-controls.spec.md「寬度軸」。
+export type FieldWidth = 'fill' | 'hug'
 
 // ── Menu List Min Height ─────────────────────────────────────────────────────
 // SelectMenu / Select / Combobox 共用的 CommandList minHeight 計算。

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

@@ -1,3 +1,4 @@
+// @internal — DS-internal 單元(Field 家族 chrome 基底,consumer 用 Field/Input 等 wrapper 不直用);不隨 index.ts re-export 進 npm public surface。
 // @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.
 import { cva } from 'class-variance-authority'
 
@@ -11,9 +12,11 @@ import { cva } from 'class-variance-authority'
 //   readonly — bg-readonly(neutral-2), 無邊框, 文字正常色(input chrome 但鎖定;token 獨立於 disabled)
 //   disabled — bg-disabled(neutral-2), 無邊框, 文字灰化
 //
-// 2 種視覺外殼(variant):
+// 2 種視覺外殼(variant;2026-07-09 `bare` 退役後):
 //   default — 完整 chrome(form input 場景)
-//   bare    — 透明 chrome(cell-as-input substrate / Toolbar inline editing)
+//   naked   — cell-as-input substrate(DataTable);**edit×naked 自畫 border-based state machine**
+//              (border-border → hover:border-border-hover → focus-within:border-primary → error 紅框);
+//              display/readonly/disabled×naked 用 transparent border,由 host cell 提供視覺邊框
 //
 // 高度:固定 h = field-height token(rem),與 Button 共用同一組 token。
 
@@ -32,7 +35,9 @@ export const fieldWrapperStyles = cva(
     // 修一處全 Field family 跟動(Input/Select/Combobox/DatePicker/TimePicker/LinkInput/
     // Textarea/NumberInput/PeoplePicker)— 對齊 M17/M19/M23 一處 SSOT + data-table.spec.md:233
     // 「禁硬裁無 ellipsis」DS canonical + MUI X DataGrid / Ant Table column.ellipsis 共識。
-    'inline-flex items-center w-full min-w-0 rounded-md',
+    // 2026-07-08 width 軸:`w-full` 從 base 移入 `width` variant(fill = 原行為 default,
+    // 零回歸;hug = w-fit 依內容收縮)。詳 field-controls.spec.md「寬度軸(width: fill / hug)」。
+    'inline-flex items-center min-w-0 rounded-md',
     'text-foreground font-normal',
     'transition-colors duration-150',
   ],
@@ -47,13 +52,13 @@ export const fieldWrapperStyles = cva(
       variant: {
         // default — 完整 Field wrapper chrome(bg-surface、明顯 border、hover/focus 回饋)
         default: '',
-        // bare — 透明 variant,hover / focus 才出現 border。適用 Toolbar inline editing
-        // (FileViewer zoom input / chart config / rich text toolbar number input 等)。
-        // 世界級對照:VS Code settings / Figma toolbar number / Notion prop input。
-        bare: '',
-        // naked — 完全無 variant,hover/focus 也不出 border。適用 cell-as-input
-        // (host cell 自管 border + focus visual,內部 input 純文字承載)。
+        // naked — cell-as-input(Notion / Airtable / Excel canonical)。**edit×naked 自畫** border +
+        // hover:border-border-hover + focus-within:border-primary + error 紅框(v14 border-based state
+        // machine,見下方 compoundVariants L182-196);display/readonly/disabled×naked 用 transparent
+        // border 由 host cell 提供視覺邊框,內部 input 純文字承載。
         // 世界級對照:Airtable / Notion / Excel / Google Sheets cell editing。
+        // (2026-07-09 `bare` variant 已退役 — 見 field-types.ts FieldVariant 註解;
+        //  被 import 的 `bareInputStyles` 常數是內層 input 重置樣式、與此不同物、保留。)
         naked: '',
       },
       size: {
@@ -61,6 +66,19 @@ export const fieldWrapperStyles = cva(
         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',
       },
+      // width(2026-07-08 user 拍板,正交軸):寬度軸 — 只改寬度,chrome / hover / focus /
+      // error / mode compoundVariants 全部不動(user verbatim「框線和互動和樣式都不變,
+      // 只有寬度有變而已 … 把 field 和 value 的寬度都改成 hug」)。
+      //   fill(default)— `w-full` 填滿容器 = 與移軸前 base 完全等價(零回歸不變量)
+      //   hug — `w-fit` 依內容收縮:value 寬 + 各 slot 元素寬 + gap + field 內 padding;
+      //         `max-w-full` 保證窄容器不溢出(min-w-0 保留,仍可 truncate)
+      // Benchmark(M22):shadcn v4 SelectTrigger 預設 `w-fit`
+      //   https://raw.githubusercontent.com/shadcn-ui/ui/main/apps/v4/registry/new-york-v4/ui/select.tsx
+      //   Radix Select Trigger intrinsic sizing https://www.radix-ui.com/primitives/docs/components/select
+      width: {
+        fill: 'w-full',
+        hug: 'w-fit max-w-full',
+      },
       // error(2026-07-04 Q1 拍板,SSOT 集中):原散在各控件的 error border classes 因
       // focus-within:!border-primary(!important)被蓋 = dead code(聚焦永遠藍)。
       // Benchmark 實查證偽舊宣稱:MUI(紅框加粗)/ Ant(紅框紅 glow)/ Polaris(紅 border
@@ -119,7 +137,18 @@ export const fieldWrapperStyles = cva(
       {
         mode: 'readonly',
         variant: 'default',
-        className: 'bg-readonly border border-transparent',
+        // 2026-07-09 A11y fix(WCAG 2.4.7 Focus Visible):readonly **有值** 渲染 native `<input readOnly>`
+        // = 可 Tab 聚焦、可選取/複製,但原 compound 無任何 focus 指示 → 鍵盤使用者聚焦不可見 = 違反。
+        // 補 focus ring 採 **ring idiom**(`ring-2 ring-ring ring-offset-1`,與 Button/Checkbox/Tabs/
+        // Switch 同一套 focus-visible canonical;`--ring == --primary` semantic.css:334)而非 edit mode
+        // 的 `border-primary` idiom —— readonly 邊框 transparent 無可染;且 ring 語義 = 「可聚焦但非文字
+        // 輸入」(對齊 button/tab/checkbox 這類 focusable-非-text-entry 控件的視覺語言)。
+        // `:has(:focus-visible)`:readonly 渲 native `<input readOnly>`。⚠️ 瀏覽器對 text-entry 控件的
+        // :focus-visible 啟發式在滑鼠點擊時**亦 match**(text input 恆視為 focus-visible,對齊
+        // field-controls.spec.md「Focus 行為」段『文字輸入永遠 focus-visible、CSS 無法區分點擊與 Tab』),
+        // 故點擊 readonly input 也會顯 ring,勿宣稱僅鍵盤觸發(button 的 focus-visible 才滑鼠不觸發,
+        // input 不同;真要滑鼠抑制需 JS 追蹤 input modality,屬 API 擴充)。
+        className: 'bg-readonly border border-transparent [&:has(:focus-visible)]:ring-2 [&:has(:focus-visible)]:ring-ring [&:has(:focus-visible)]:ring-offset-1',
       },
       {
         // 2026-05-13 R3.5(per codex Q3 verdict + user 拍「想盡辦法 auto-handle prereq」):
@@ -130,42 +159,14 @@ export const fieldWrapperStyles = cva(
         variant: 'default',
         className: 'bg-disabled border border-transparent cursor-not-allowed',
       },
-      // bare variant chrome by mode
-      {
-        mode: 'edit',
-        variant: 'bare',
-        className: [
-          'bg-transparent border border-transparent',
-          'hover:border-border',
-          // 同 default chrome v13.3 SSOT:focus-within !important 強制勝過 data-state
-          //(2026-07-04 Q1:同 default,focus 藍移到 error:false compound)
-          'data-[state=open]:border-border',
-        ],
-      },
-      { mode: 'edit', variant: 'bare', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },
+      // (2026-07-09 `bare` variant 退役:原 edit×bare / edit×bare×error compounds 已移除。)
       // error chrome(mode=edit 限定,variant 不分 — naked cell 內 error 同樣紅框,保留既有控件層行為):
       {
         mode: 'edit',
         error: true,
         className: 'border-error hover:border-error-hover focus-within:!border-error focus-within:hover:!border-error',
       },
-      {
-        mode: 'display',
-        variant: 'bare',
-        // bare + display:cell-as-input default state(無 variant,完全融入 cell;hover/focus 才有 affordance 等 user 點下去切 edit mode)
-        className: 'bg-transparent border border-transparent',
-      },
-      {
-        mode: 'readonly',
-        variant: 'bare',
-        className: 'bg-transparent border border-transparent',
-      },
-      {
-        // 2026-05-13 R3.5:移除 `opacity-disabled` blanket(per Avatar self-dim canonical)
-        mode: 'disabled',
-        variant: 'bare',
-        className: 'bg-transparent border border-transparent cursor-not-allowed',
-      },
+      // (2026-07-09 `bare` variant 退役:原 display×bare / readonly×bare / disabled×bare compounds 已移除。)
       // naked variant — cell-as-input substrate(Notion / Airtable / Excel canonical)
       //
       // ── 2026-05-06 v14:revert v12 → v9 baseline + keep v13.3 ──
@@ -248,6 +249,7 @@ export const fieldWrapperStyles = cva(
       mode: 'edit',
       variant: 'default',
       size: 'md',
+      width: 'fill',
       error: false,
     },
   }
@@ -351,12 +353,18 @@ export const nakedCellEditableDisplayHover = 'hover:outline hover:outline-1 hove
 //   - 多行 wrapper items-start  → slot 1lh 鎖頂 = 第一行中線
 //   不需 conditional `group-data-[row-mode=auto]/cell:` — 我前 v4 自加的 conditional 是過度設計。
 //
-// State ring 3 const 仍留(下方)— 是 Field naked 專屬,MenuItem / TreeView 用 bg hover 不用 outline。
+// State ring 唯一 const `nakedCellEditableDisplayHover` 仍留(下方 L332,見其自述「sole remaining ring const」)— 是 Field naked 專屬,MenuItem / TreeView 用 bg hover 不用 outline。
 // `nakedCellRowModeAlign`(wrapper 級)仍留 — 是 cell-context row-mode → wrapper alignment 適配,正交 slot 級。
 
 // ── Empty Value Display ─────────────────────────────────────────────────────
 
-export const EMPTY_DISPLAY = '—'
+// 2026-07-08 user 拍板(verbatim「我從頭到尾哪裡有說要用全形的」):空值符號 = **半形 hyphen
+// `-`(U+002D)**，非全形 em dash `—`(U+2014)。不可編輯(readonly / standalone display /
+// table 不可編輯 cell)空值一律此符號 + `text-fg-muted`。分流邏輯 SSOT = field-context.ts
+// `useFieldEmptyDisplay()`(table-cell 可編輯 → 空白；其餘 → 本常數)。
+// 世界級對照:Ant ProTable `columnEmptyText` 預設 `'-'`(U+002D 半形)
+//   https://github.com/ant-design/pro-components/blob/master/src/table/Table.tsx
+export const EMPTY_DISPLAY = '-'
 
 /**
  * 2026-05-14 I2 fix(per field-controls.spec.md contract (e) display typography canonical):

package/src/components/Field/field.anatomy.stories.tsx

@@ -38,7 +38,7 @@ export const Overview: Story = {
             </Field>
           </FieldGroup>
         </div>
-        <p className="text-footnote text-fg-muted mt-3">FieldLabel(必有)+ Control(必有)+ FieldDescription(選填)+ FieldError(僅 invalid 時顯示)</p>
+        <p className="text-footnote text-fg-muted mt-3">FieldLabel(必有)+ Control(必有)+ FieldDescription(選填)+ FieldError(consumer 傳 error 文字時渲染;children 有值即顯、固定 role=alert,非讀 Field.invalid 自動隱藏)</p>
       </div>
 
       <div>
@@ -73,7 +73,7 @@ export const Overview: Story = {
                 ['disabled', 'boolean', 'false', 'context.disabled 傳給 control'],
                 ['size', "'sm' | 'md' | 'lg'", "'md'", 'context.size 傳給 input-class control(Input / NumberInput / Select);primitive 不讀'],
                 ['mode', "'edit' | 'display' | 'readonly' | 'disabled'", "'edit'", 'context.mode 傳給 Field Controls'],
-                ['variant', "'default' | 'bare' | 'naked'", "'default'", "視覺外殼:default 含 border+bg / bare hover-reveal(toolbar inline edit)/ naked 無 chrome(DataTable cell substrate)"],
+                ['variant', "'default'", "'default'", "視覺外殼(公開型別僅 'default',2026-07-14 收窄;naked = @internal FieldVariantInternal):default 含 border+bg / naked = DataTable cell substrate:edit×naked 自畫 border-based state machine(rest/hover/focus/error),display/readonly/disabled×naked 用 transparent border;2026-07-09 `bare` 退役"],
                 ['controlLayout', "'inline' | 'block'", '(自動偵測)', '逃生艙:覆寫 control area 佈局(consumer 手寫 JSX 當 control 無法偵測時用)'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
@@ -248,8 +248,11 @@ export const OrientationMatrix: Story = {
               <Switch defaultChecked className="ml-0" />
             </Field>
             <Field orientation="horizontal">
-              <FieldLabel>個人檔案公開</FieldLabel>
-              <Checkbox label="允許搜尋引擎索引" />
+              <FieldLabel>允許搜尋引擎索引</FieldLabel>
+              {/* 單一布林欄位只用 FieldLabel,不再給 Checkbox 傳 label —— field.spec.md 禁止事項
+                  「不得同時放 FieldLabel 和 primitive label」(Field context 會抑制 primitive label,
+                  傳了不生效且重複宣告);與上方 Switch 列同款 pattern */}
+              <Checkbox />
             </Field>
           </FieldGroup>
         </div>
@@ -411,9 +414,9 @@ export const ColorMatrix: Story = {
               </tr>
               <tr>
                 <Td mono>FieldError</Td>
-                <Td>—(不渲染)</Td>
+                <Td>—(無 error children → 不渲染;children-gated,非 invalid-gated)</Td>
                 <Td><TokenCell token="--error-text" display="error-text" /></Td>
-                <Td>—</Td>
+                <Td><TokenCell token="--error-text" display="error-text(不 dim)" /></Td>
               </tr>
               <tr>
                 <Td mono>Control border(傳給 Field Controls)</Td>

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

@@ -418,7 +418,7 @@ Field 內的資料輸入控件（Input / NumberInput / DatePicker / Select / Com
 | **L3 State machine** | **繼承 Field default v13.3**(↑ 上方 SSOT)| 不重定義 |
 | **L4 Display hover** | `field-wrapper.tsx` `nakedCellEditableDisplayHover` | editable cell display mode `outline-1 outline-offset:-1 outline-[var(--cell-hover-outline-color,var(--border-hover))]`(cell wrapper outline;2026-05-10 Slice D:spreadsheet overlay 啟用時 DataTable cell host 可 set `--cell-hover-outline-color: transparent` 抑制 outline、讓 overlay layer 接管 hover ring paint,fallback 即 `--border-hover` 既有行為不變)。**v15.13 design intent(user-accepted 2026-05-07)**:hover ring 蓋 cell.borderRight。**known asymmetry**(2026-05-09 user 重抓):只 **right** 邊 outline 跟 cell own border-r 同位置覆蓋成 1 條;top/left/bottom 邊 outline 在 cell.outer 內 1px,grid lines(前 row border-b / 前 cell border-r / row 自己 border-b 在 cell.outer 外 1px)露出 → 視覺 4 邊不對稱。**Pending design decision**(等 user 拍板才 ship):4 邊都蓋(spec 1 selection-style)vs 4 邊都不蓋(spec 2 inset 1px)vs 維持現狀。三層 SSOT:state source = cell wrapper / paint owner = 混合(hover=cell / edit=Field)/ grid divider = DataTable own |
 | **L5 Position(v14,2026-05-06 revert v12)** | naked compoundVariant flow | Field 留 layout flow,**不**用 `!absolute`(v12 absolute 跟 autoRowHeight 不相容)。視覺接受 cell `border-r grid` + Field border 2px 雙線;cell border-r divider 永遠保留(對齊 L4 Invariant divider-owner / editor-owner 分離)|
-| **L6 Cell trigger indicator(v15,2026-05-09)** | naked-display branch + `showDisplayEndIcon?: boolean` opt-in | DataTable cell-registry 顯式傳 `showDisplayEndIcon` → Field component 內部 `<ItemSuffix>` 渲對應 trigger icon(Select/Combobox/PeoplePicker → ChevronDown / DatePicker → CalendarIcon / TimePicker → Clock / LinkInput 例外無 suffix)。table 外用法不傳此 prop = 純展示無 icon。詳 `.claude/planning/cell-indicator-ssot-rfc.md`。|
+| **L6 Cell trigger indicator(v16,2026-07-08 user 拍板 A 案)** | naked-display branch + `showDisplayEndIcon?: boolean` opt-in(**default off,production 不再傳**)| **display 態零恆顯型別 icon** — editable affordance 統一 = L4 hover outline。Benchmark 6/6(Ant editable-cells 純文字+hover border / MUI X singleSelect display 純文字 / AG Grid 無內建 indicator / Atlaskit v2.0.0 移除 hover-pencil 後 9 版未回歸 / Notion / Airtable click-to-edit)display 態皆無恆顯 icon;唯一反例 Google Sheets Chip/Arrow 為 spreadsheet 域可選檔位。prop 保留為 spreadsheet-flavored 消費端 opt-in 逃生門:傳 true → `<ItemSuffix>` 渲型別 icon(Select/Combobox/PeoplePicker → ChevronDown / DatePicker → Calendar / TimePicker → Clock / **LinkInput 例外 = wrapper-only 無 icon**)。cell-registry 現況:6 picker 站不傳;url 站傳 `isEditable === true`(取 wrapper chrome 對齊 edit Input,非 icon)。edit 態 chevron 照舊(edit-trigger 通道,不受此 prop 管)。**值內容 vs affordance 分層(2026-07-08 user Q2 拍板)**:值內容(`selectedItemRenderer` 輸出 / avatar / type icon 等語意呈現)歸 value renderer,display 態照常渲染,恆顯**不**違反本條;本條管的是 affordance(chevron / pencil / outline)。前身 v15 恆顯制(2026-05-10/06-26 拍板)由本輪 benchmark 重判推翻。詳 `.claude/planning/cell-indicator-ssot-rfc.md`。|
 
 **前身 retire**:v4-v8 `outline-2` 平行 state(已下沉 L3)/ v9 border-only(focus 跟 open specificity tie)/ per-control `open && 'border-primary'`(v13.3 retire)/ `nakedCell{Hover,Focus,Open}Ring` 三 const / `nakedCell{Prefix,Suffix}Slot`(下沉 L1)/ **v12 `!absolute -inset-px` seamless grid**(2026-05-06 revert — autoRowHeight 不相容)/ **DataTable parallel `getEditIndicator`**(2026-05-09 D-path retire — 由 Field naked-display 透過 `showDisplayEndIcon` opt-in 自渲 ItemSuffix,跨元件 SSOT 統一)。
 

package/src/components/Field/field.stories.tsx

@@ -86,7 +86,7 @@ export const StateCascade: Story = {
         </div>
       </div>
       <div>
-        <p className="text-body-sm font-medium text-fg-secondary mb-3">{'<Field mode="readonly"> — 鎖定表單:文字控件灰框;boolean/單選 = 灰框 + ✓/—/選中項(2026-06-12 拍板);Rating 星星鎖定、Slider 鎖互動保留視覺'}</p>
+        <p className="text-body-sm font-medium text-fg-secondary mb-3">{'<Field mode="readonly"> — 鎖定表單:文字控件灰框;boolean/單選 = 灰框 + 勾/叉 icon/選中項(2026-06-12 拍板);Rating 星星鎖定、Slider 鎖互動保留視覺'}</p>
         <div className="flex flex-wrap gap-x-8 gap-y-4 max-w-3xl">
           <Field mode="readonly" className="w-44"><FieldLabel>負責人</FieldLabel><Input value="王小明" onChange={() => {}} /></Field>
           <Field mode="readonly" className="w-44"><FieldLabel>同意條款</FieldLabel><Checkbox checked /></Field>

package/src/components/Field/field.tsx

@@ -110,7 +110,8 @@ export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
   /**
    * 視覺外殼(2026-05-05)。
    * - `default`(預設)— 含 border + bg(一般 form input)
-   * - `bare` — 透明 variant,hover/focus reveal(cell-as-input substrate;VS Code/Figma toolbar idiom)
+   * - `naked` — cell-as-input(@internal;不在公開 FieldVariant 型別 — 2026-07-14 收窄至 FieldVariantInternal;2026-07-09 `bare` 退役)。edit×naked 自畫 border-based state
+   *   machine(rest/hover/focus/error);display/readonly/disabled×naked 用 transparent border,host cell 提供視覺邊框
    *
    * 透傳機制:Field 一次宣告,所有 child Field control 自動繼承(per-control prop override 可覆寫)。
    */

package/src/components/Field/form-validation.spec.md

@@ -41,7 +41,7 @@
 ### Submit 驗證
 
 7. **Submit 驗證全部**——點擊 submit 時對所有欄位執行驗證(不依賴個別 field 的 blur 狀態)
-8. **Anchor 到第一個錯誤**——若有任何欄位出錯,scroll 並 focus 到第一個錯誤欄位(**「第一個」= DOM 視覺順序**,非 validate key 宣告順序;對齊瀏覽器原生 reportValidity + react-hook-form shouldFocusError,2026-07-07 code 同步)。多次 submit 重試時,每次都重新驗證全部欄位並重新計算「第一個錯誤」(rule 7 的自然結果),不保持上次 anchor 位置
+8. **Anchor 到第一個錯誤**——若有任何欄位出錯,scroll 並 focus 到第一個錯誤欄位(focus 僅對可由 DOM `name` 定位的 native input 生效,非 native 控件(Select / Combobox / RadioGroup 等)fallback 為 scroll + error 視覺,見下方「v1 邊界」(b);**「第一個」= DOM 視覺順序**,非 validate key 宣告順序;對齊瀏覽器原生 reportValidity + react-hook-form shouldFocusError,2026-07-07 code 同步)。多次 submit 重試時,每次都重新驗證全部欄位並重新計算「第一個錯誤」(rule 7 的自然結果),不保持上次 anchor 位置
 9. **Async / cross-field 驗證 defer 到 submit**——某些驗證無法在 blur 當下完成(如「名稱是否重複」需要 API 查詢、跨欄位邏輯如「結束日不得早於開始日」),這些在 submit 時統一判斷。若有錯誤,同樣 anchor 到第一個出錯欄位。
 
 **Double-submit 防護(2026-07-05 D4 codify,規則 9 的必然配套)**:async onSubmit 進行期間,重複 submit(連點按鈕 / 連按 Enter)一律忽略——否則業務層被並發呼叫兩次(重複建立資源的經典事故)。submit 期間狀態以 `isSubmitting` 暴露(餵 Button loading / disabled;`submitDisabled` 同步為 true);onSubmit 拋錯時先復位 `isSubmitting` 再讓錯誤原樣上拋(不吞錯,表單回到可重送狀態)。對齊 react-hook-form `formState.isSubmitting` / Polaris / Mantine form submitting 內建。 <!-- @benchmark-unverified -->
@@ -151,8 +151,8 @@ Email 格式 / URL 格式 / 必填等「single-field 純 syntax」blur 即可判
 Form validation 的 ARIA / 鍵盤行為(對齊 WCAG 3.3.1 Error Identification + 3.3.3 Error Suggestion):
 
 - **Error message ARIA**:`<FieldError>` 容器 id = `{fieldId}-error`(fieldId 為 Field 的 `id` prop / `useId`,field.tsx:174),控件經 Field context 自動接 `aria-errormessage`(有 error 時指向 errorId)+ `aria-invalid="true"`;`aria-describedby` 保留給 FieldDescription(descriptionId)。SR 在 focus field 時可得 label + error 完整資訊;接線 SSOT 見 `field.spec.md`「驗證與 aria 屬性」段(input.tsx:187-190)
-- **Submit error scroll**:submit 失敗後,focus 自動 jump 到第一個 invalid field(`field.focus()` + `scrollIntoView({block: 'center'})`);對齊 Material / Atlassian 慣例 <!-- @benchmark-unverified -->
-- **Error live region**:跨欄位 / async error 用 `aria-live="polite"` 容器宣告 — SR 在空閒時讀出,不中斷使用者打字
+- **Submit error scroll**:submit 失敗後,focus 自動 jump 到第一個 invalid field(`field.focus()` + `scrollIntoView({block: 'center'})`;focus 僅對 DOM `name`-locatable native input 生效,非 native 控件 fallback 為 scroll + error 視覺,見「v1 邊界」(b));對齊 Material / Atlassian 慣例 <!-- @benchmark-unverified -->
+- **Error 宣告**:`<FieldError>` 為 `role="alert"`(隱含 `aria-live="assertive"`,field.tsx:468)——error 文字一出現即由 SR 宣讀;children 有值才渲染(children-gated,非讀 Field.invalid)。目前**無**獨立 `aria-live="polite"` 容器,跨欄位 / async error 亦透過對應 field 的 `<FieldError>` 呈現
 - **Required indicator**:label 的 `*` 為純視覺、對讀屏隱藏(`aria-hidden="true"`,field.tsx:395);required 語意由內部輸入控件的 `aria-required`(input.tsx:188)承擔,避免讀屏讀出「asterisk」語義不清
 - **Color-only error 警告**:error border 紅色之外必有文字訊息(WCAG 1.4.1 不僅靠顏色)— 由 `<FieldError>` 文字承擔;DS **不**在 input 內放 error 狀態 icon(見 `field-controls.spec.md`「禁止事項」)
 

package/src/components/FieldControlGroup/field-control-group.principles.stories.tsx

@@ -38,7 +38,7 @@ export const UsageGuidance: Story = {
         </ul>
         <div className="mt-3">
           <FieldControlGroup block>
-            <Input className="flex-1" startIcon={Search} placeholder="搜尋..." />
+            <Input className="flex-1" startIcon={Search} placeholder="搜尋..." aria-label="搜尋" />
             <Button variant="primary">搜尋</Button>
           </FieldControlGroup>
         </div>
@@ -101,8 +101,8 @@ export const UsageGuidance: Story = {
         <Field>
           <FieldLabel>聯絡電話</FieldLabel>
           <FieldControlGroup block>
-            <Select className="!w-[88px]" options={CODES} value="+886" onChange={() => {}} />
-            <Input className="flex-1" placeholder="912 345 678" />
+            <Select className="!w-[88px]" options={CODES} value="+886" onChange={() => {}} aria-label="國碼" />
+            <Input className="flex-1" placeholder="912 345 678" aria-label="電話號碼" />
           </FieldControlGroup>
         </Field>
         <p className="text-caption text-fg-muted mt-2">Field label / description / error 對 group 整體生效;children 的 size 各自從外層 Field context 繼承(FCG 不傳遞 size)。</p>
@@ -111,9 +111,9 @@ export const UsageGuidance: Story = {
       <section>
         <h2 className="text-body-lg font-bold mb-3">Mode B — Filter row 場景</h2>
         <FieldControlGroup block>
-          <Select className="!w-[140px]" options={FIELDS} value="name" onChange={() => {}} />
-          <Select className="!w-[120px]" options={OPS} value="contains" onChange={() => {}} />
-          <Input className="flex-1" defaultValue="無線滑鼠" />
+          <Select className="!w-[140px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+          <Select className="!w-[120px]" options={OPS} value="contains" onChange={() => {}} aria-label="篩選運算子" />
+          <Input className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
         </FieldControlGroup>
       </section>
     </div>