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

package/src/components/InlineEdit/inline-edit.tsx

@@ -1,30 +1,33 @@
 // ── 消費的 SSOT ──
-// - components/Field/field-controls.spec.md(「Field 框架地圖」段:InlineEdit = read↔edit 疊在 Field 之上;edit-in-place)
+// - components/Field/field-controls.spec.md(「軸二 就地編輯 host」段:InlineEdit = view↔edit 二態疊在 Field 之上;edit-in-place + editable 閘)
 // - components/Field/field-edit-keys.ts(makeEditSettleKeyHandler = Enter/Esc + 中文 IME guard 結算 SSOT,與 DataTable cell 同源)
+// - components/Field/field-wrapper.tsx(fieldViewGeometry = view 幾何 class SSOT〔純值/標題路徑〕;fieldDisplayTextClass = view 字級)
 // - components/Input/input.tsx / Textarea/textarea.tsx(預設 renderEdit;不重刻 input chrome)
-// - components/Field/field-context.ts(FieldSize 型別)
-// - tokens/uiSize/uiSize.css(--field-px 水平內距 SSOT / --field-height-{sm,md,lg} read 態高度)
+// - components/Field/field-context.ts(useFieldContext / useResolvedFieldSize;接 size/orientation/labelId cascade)
+// - tokens/uiSize/uiSize.css(--field-px 水平內距 SSOT / --field-height-{sm,md,lg} view 態高度)
 // - tokens/color/color.spec.md(bg-neutral-hover = hover 回饋)
-// - components/Field/field-wrapper.tsx(read focus = border-primary,消費 Field edit focus 藍框語言;非 Button ring)
 // - 世界級對照(泛型 readView/editView 就地編輯 + read 態底色 tint + 隱形 Pressable):
-//   Atlassian inline-edit(readView/editView 兩 render prop + 泛型 <FieldValue>)
-//     https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/types.tsx
-//   read-view hover = 背景 tint 非邊框 + 隱形 Pressable 供鍵盤 focus+Enter:
+//   Atlassian inline-edit(readView/editView 兩 render prop + read wrapper 靠負邊距對齊 edit)
 //     https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx
+//   就地編輯無 disabled 態(鎖定 = 純 view 無入口、不灰化):MUI X isCellEditable / cellMode
+//     https://mui.com/x/react-data-grid/editing/ + AG Grid editable https://www.ag-grid.com/react-data-grid/cell-editing/
 //
-// ── 型別化 read / 多行(2026-07-09 L2,edit-in-place SSOT 研究落地)──
-// InlineEdit 現為泛型 <T>(非只 string)。**格式化 read view 的 SSOT 鐵律**:renderRead 要顯示
-// Tag / 日期 / label 等格式化值時,**渲染對應 Field 控件的 `mode="display"`**(如 `<Select mode="display"
-// display="tag">`),**不可自刻 Tag / 格式化**——「select 值 → Tag」的 SSOT 住在 Select 的 display mode
-// (= DataTable cell 消費的同一份)。這保證 read 與 edit 用同一個控件、格式零分歧。多行(multiline)
-// 供 Jira description 類欄位。
+// ── Model A(2026-07-16 round16,user GO)──────────────────────────────────────
+// InlineEdit **不自帶 geometry cva**(消 M17 重複):
+//   - 值-格式化(Select→Tag / Date / avatar)→ renderRead 委派 `<Control mode="view">`,幾何 + 內部間距
+//     皆由控件 view×default 提供(read=edit 同一顆 → 天生一致、多 tag/avatar 間距零偏移)。
+//   - 純值 / 標題 `<Tag as="h1">` → 套 `fieldViewGeometry(size, multiline)` helper(= view×default 幾何 SSOT)。
+//   InlineEdit 本體只給:`-mx`(orientation-aware,拉到欄左緣,= 上方 read-view 負邊距對照)+ hover bg + focus 藍框 + 隱形 Pressable。
+//   read↔edit 零跳 = view 與 edit 同一顆控件、只差 chrome。
+// **格式化 read 鐵律**:renderRead 要顯示 Tag/日期/label,**渲染對應控件的 `mode="view"`**
+//   (如 `<Select mode="view" display="tag">`),不可自刻 —— 格式化 SSOT 住在該控件的 view mode。
 import * as React from 'react'
 import { cn } from '@/lib/utils'
 import { Input } from '@/design-system/components/Input/input'
 import { Textarea } from '@/design-system/components/Textarea/textarea'
 import type { FieldSize } from '@/design-system/components/Field/field-context'
-import { cva } from 'class-variance-authority'
-import { fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
+import { useFieldContext, useResolvedFieldSize, FieldSurfaceProvider } from '@/design-system/components/Field/field-context'
+import { fieldDisplayTextClass, fieldViewGeometry } from '@/design-system/components/Field/field-wrapper'
 import { makeEditSettleKeyHandler } from '@/design-system/components/Field/field-edit-keys'
 
 // ── Types ───────────────────────────────────────────────────────────────────
@@ -35,13 +38,13 @@ export interface InlineEditRenderProps<T = string> {
   value: T
   /** 草稿變更 */
   onChange: (next: T) => void
-  /** 提交草稿 → onCommit(next) + 回 read 態 */
+  /** 提交草稿 → onCommit(next) + 回 view 態 */
   commit: () => void
-  /** 放棄草稿 → 回 read 態不 commit */
+  /** 放棄草稿 → 回 view 態不 commit */
   cancel: () => void
   /** 進 edit 態時自動 focus 控件 */
   autoFocus: boolean
-  /** 尺寸(cascade 給控件,與 read 態高度對齊) */
+  /** 尺寸(cascade 給控件,與 view 態高度對齊) */
   size: FieldSize
   /** 控件無障礙標籤(= label prop) */
   'aria-label'?: string
@@ -50,78 +53,57 @@ export interface InlineEditRenderProps<T = string> {
 type ReadTag = 'span' | 'p' | 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
 
 export interface InlineEditProps<T = string> {
-  /** 已提交的欄位值(read 態顯示;edit 進入時作草稿初值)。泛型:string / number / string[] / PersonValue 等 */
+  /** 已提交的欄位值(view 態顯示;edit 進入時作草稿初值)。泛型:string / number / string[] / PersonValue 等 */
   value: T
   /** 提交回呼 —— blur / Enter 且草稿有變更時觸發 */
   onCommit: (next: T) => void
   /**
-   * 自訂 edit 態控件(換 Textarea / Select / DatePicker 等 Field 控件)。
-   * 不傳則預設:multiline → `<Textarea>`,否則 `<Input>`(僅 T=string 時預設有效;非 string 值必傳此 prop)。
+   * 自訂 edit 態控件(換 Textarea / Select / DatePicker 等 Field 控件,必用 `mode="edit"`)。
+   * 不傳則預設:multiline → `<Textarea mode="edit">`,否則 `<Input mode="edit">`(僅 T=string 時預設有效;非 string 值必傳此 prop)。
    */
   renderEdit?: (props: InlineEditRenderProps<T>) => React.ReactNode
   /**
-   * 自訂 read 態格式化顯示。不傳則顯示 `String(value)`(空值顯 placeholder)。
-   * **SSOT 鐵律**:要顯示 Tag / 日期格式 / option label 等,**渲染對應控件的 `mode="display"`**
-   * (如 `renderRead={(v) => <Select mode="display" display="tag" value={v} options={opts} />}`),
-   * 不可自刻 —— 格式化 SSOT 住在該控件的 display mode(見檔頭)。
+   * 自訂 view 態格式化顯示。不傳則顯示 `String(value)`(空值顯 placeholder)。
+   * **SSOT 鐵律**:要顯示 Tag / 日期格式 / option label 等,**渲染對應控件的 `mode="view"`**
+   * (如 `renderRead={(v) => <Select mode="view" display="tag" value={v} options={opts} />}`),
+   * 不可自刻 —— 格式化 + 內部間距 SSOT 住在該控件的 view mode(見檔頭 Model A)。
    */
   renderRead?: (value: T) => React.ReactNode
-  /** 多行欄位(Jira description 類):read 態換行 + 預設 edit 態用 `<Textarea>`,Enter=換行、Cmd/Ctrl+Enter 或 blur 提交 */
+  /** 多行欄位(Jira description 類):view 態換行 + 預設 edit 態用 `<Textarea>`,Enter=換行、Cmd/Ctrl+Enter 或 blur 提交 */
   multiline?: boolean
-  /** 欄位人類可讀名稱 —— 組 read 按鈕 aria-label(「編輯 {label}」)+ 控件 aria-label */
+  /**
+   * 是否可編輯(預設 true)。false → view 態無 hover 入口、無藍框、不可點進 edit(對齊世界級就地編輯
+   * **無 disabled 態**,鎖定 = 純 view 無入口、**不灰化**;cite 見檔頭 MUI X / AG Grid URL)。
+   * 永久唯讀資料 → 用 `<Control mode="view">` 或此 prop false;不用 disabled。
+   */
+  editable?: boolean
+  /** 欄位人類可讀名稱 —— 組 view 按鈕 aria-label(「編輯 {label}」)+ 控件 aria-label */
   label?: string
-  /** 空值時 read 態顯示的提示文字(fg-muted) */
+  /** 空值時 view 態顯示的提示文字(fg-muted) */
   placeholder?: string
-  /** 尺寸 —— read 態最小高度 + 預設 Input 尺寸(與 Field 家族一致) */
+  /** 尺寸 —— view 態最小高度 + 預設 Input 尺寸(不傳則經 useResolvedFieldSize 接 Field size cascade,standalone fallback sm) */
   size?: FieldSize
-  /** read 態語意標籤(標題場景傳 'h1'/'h2' 維持文件大綱;預設 'span') */
+  /** view 態語意標籤(標題場景傳 'h1'/'h2' 維持文件大綱;預設 'span') */
   as?: ReadTag
-  /** read 態文字樣式(如標題 `text-h4 font-bold`) */
+  /** view 態文字樣式(如標題 `text-h4 font-bold`) */
   readClassName?: string
   /** 外層容器 className */
   className?: string
 }
 
-// ── Read-view geometry cva ────────────────────────────────────────────────────
-// base = 排版結構;size variant = min-height(與 edit 態 Field 高度一致,降低態切換位移)。
-// multiline variant:單行 → `items-center`(文字垂直置中於 field-height);多行 → `items-start py-1.5`
-//   (頂對齊 + 上下內距,對齊 Textarea `py-2` 多行閱讀語意,內容換行往下長)。
-// read 態幾何典範對照(M22 cite,2026-07-09 逐行核對原始碼,見檔頭 read-view URL):
-//   hover = 底色 tint 非邊框;focus = 實線 solid border;wrapper 恆帶透明 border 預留邊框盒。
-const inlineEditReadStyles = cva(
-  // relative(疊隱形 Pressable)/ border-transparent(預留 1px 邊框盒 → 態切換零位移;focus 才染色)/
-  // px-[--field-px](文字↔底色水平內距 = Field 內距 SSOT,read=edit x 位置零跳)/ hover 底色 tint /
-  // [&:has(button:focus-visible)]:border-primary(鍵盤 focus = Field edit 藍框語言,非 Button ring)。
-  'relative flex rounded-md border border-transparent px-[var(--field-px)] transition-colors duration-150 hover:bg-neutral-hover [&:has(button:focus-visible)]:border-primary',
-  {
-    variants: {
-      size: {
-        sm: 'min-h-[var(--field-height-sm)]',
-        md: 'min-h-[var(--field-height-md)]',
-        lg: 'min-h-[var(--field-height-lg)]',
-      },
-      multiline: {
-        false: 'items-center',
-        true: 'items-start py-1.5',
-      },
-    },
-    // 預設 sm + 單行(2026-07-09 user 拍板):read 態無邊框、視覺 = 純文字,尺寸過大會讓版面鬆散。
-    defaultVariants: { size: 'sm', multiline: false },
-  },
-)
-
 /**
- * InlineEdit — 就地編輯 primitive(read ↔ edit 二態,泛型 <T>)
+ * InlineEdit — 就地編輯 primitive(view ↔ edit 二態,泛型 <T>)
  *
  * 互動模型 world-class 對照見檔頭「消費的 SSOT」+ inline-edit.spec.md benchmark 表:
- * - **read 態** = 純文字 / 格式化 renderRead、寬度 fill 容器、透明邊框(預留)→ 視覺 = 純內容
- * - **hover(read)** = 灰色底色 `bg-neutral-hover` + `rounded-md`(**非邊框**)+ cursor
- * - **鍵盤 focus(read)** = 外框染 `border-primary` 藍框(Field focus 語言,非 Button ring)
- * - **click / Enter/Space** = 切 edit 態 = 真正的 Field 控件(border + focus + input);多行走 Textarea
- * - **退出**:blur / Enter → commit;Esc → cancel 還原不 commit;focus 返回 read 按鈕
+ * - **view 態** = 純文字 / 格式化 renderRead、寬度 fill 容器、透明邊框(預留)→ 視覺 = 純內容
+ * - **hover(view,editable)** = 灰色底色 `bg-neutral-hover` + `rounded-md`(**非邊框**)+ cursor
+ * - **鍵盤 focus(view,editable)** = 外框染 `border-primary` 藍框(Field focus 語言,非 Button ring)
+ * - **click / Enter/Space** = 切 edit 態 = 真正的 Field 控件(mode="edit":border + focus + input);多行走 Textarea
+ * - **退出**:blur(滑鼠)→ commit + 純 view 不搶焦;Enter(鍵盤)→ commit + 焦點回 view 按鈕 + 藍框;Esc → cancel 還原
  * - **鍵盤結算**:消費 `makeEditSettleKeyHandler`(含中文 IME guard,與 DataTable cell 同源)
+ * - **editable=false**:view 無 hover / 無 Pressable / 不可進 edit、**不灰化**(detail-pane 鎖定語意)
  *
- * read 態用隱形 Pressable(絕對定位 `<button>` 疊於內容上)—— 讓 `as="h1"` 等標題標籤保留文件大綱
+ * view 態用隱形 Pressable(絕對定位 `<button>` 疊於內容上)—— 讓 `as="h1"` 等標題標籤保留文件大綱
  * a11y,同時提供鍵盤 focus + Enter 進 edit(HTML 內容模型不允許 heading 巢狀於 button,故分離)。
  */
 function InlineEditImpl<T = string>(
@@ -131,24 +113,43 @@ function InlineEditImpl<T = string>(
     renderEdit,
     renderRead,
     multiline = false,
+    editable = true,
     label,
     placeholder,
-    size = 'sm',
+    size: sizeProp,
     as = 'span',
     readClassName,
     className,
   }: InlineEditProps<T>,
   ref: React.Ref<HTMLDivElement>,
 ) {
+  // size:接 fieldCtx.size cascade,standalone fallback sm(InlineEdit 靜態 fieldPreferredSize='sm'
+  //   讓外層 `<Field>` 自動收 sm — 見檔尾 static)。
+  const size = useResolvedFieldSize(sizeProp, 'sm')
+  // orientation:vertical(值貼 label 左緣 → 用 -mx)/ horizontal(值落內容欄左緣+field-px = 對齊 sibling 控件 → 不用 -mx)。
+  const fieldCtx = useFieldContext()
+  const orientation = fieldCtx?.orientation ?? 'vertical'
+
   const [editing, setEditing] = React.useState(false)
   const [draft, setDraft] = React.useState<T>(value)
   // draft 最新值 ref —— commit 從事件 handler 呼叫時避免 stale closure
   const draftRef = React.useRef(draft)
   // 單次結算 guard —— Enter/Esc 已結算後,unmount 觸發的 onBlur 不再重複 commit
   const finalizedRef = React.useRef(false)
-  // 鍵盤結算後把 focus 送回 read 按鈕(a11y:焦點不遺失)
+  // 鍵盤結算後把 focus 送回 view 按鈕(a11y:焦點不遺失);滑鼠 blur 不送回(不搶焦)
   const returnFocusRef = React.useRef(false)
   const readButtonRef = React.useRef<HTMLButtonElement>(null)
+  // edit 態容器 ref(pointerdown-outside 用);與 forwarded ref merge。
+  // 顯式 `| null` → mutable overload(手動賦值 .current;`useRef<T>(null)` 會匹配 readonly RefObject overload)。
+  const editContainerRef = React.useRef<HTMLDivElement | null>(null)
+  const setEditContainerRef = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      editContainerRef.current = node
+      if (typeof ref === 'function') ref(node)
+      else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = node
+    },
+    [ref],
+  )
 
   const setDraftValue = React.useCallback((next: T) => {
     draftRef.current = next
@@ -161,23 +162,47 @@ function InlineEditImpl<T = string>(
     setEditing(true)
   }, [value, setDraftValue])
 
-  const commit = React.useCallback(() => {
-    if (finalizedRef.current) return
-    finalizedRef.current = true
-    returnFocusRef.current = true
-    setEditing(false)
-    if (draftRef.current !== value) onCommit(draftRef.current)
-  }, [value, onCommit])
+  // commit(returnFocus):鍵盤結算傳 true(焦點回 view 按鈕);滑鼠 blur 傳 false(不搶焦、純 view)
+  const commit = React.useCallback(
+    (returnFocus: boolean) => {
+      if (finalizedRef.current) return
+      finalizedRef.current = true
+      returnFocusRef.current = returnFocus
+      setEditing(false)
+      if (draftRef.current !== value) onCommit(draftRef.current)
+    },
+    [value, onCommit],
+  )
 
   const cancel = React.useCallback(() => {
     if (finalizedRef.current) return
     finalizedRef.current = true
-    returnFocusRef.current = true
+    returnFocusRef.current = true // Esc = 鍵盤路徑,焦點回 view 按鈕
     setEditing(false)
   }, [])
 
-  // 結算後把 focus 送回 read 按鈕(所有結算路徑含 blur / Enter / Esc 皆 return —— commit/cancel
-  // 一律 set returnFocusRef=true;對齊 spec「任一路徑結算後 focus 送回 read 按鈕」L39/L141「焦點不遺失」)
+  // ── Exit-on-blur SSOT(2026-07-17 root cause 修:blur 後 chrome 殘留)──────────────
+  // InlineEdit **保證**任何 edit 控件(預設 Input + 自訂 renderEdit 的 Select/DatePicker/Combobox…)
+  // blur 都回 view,**不靠** consumer 在 renderEdit 自接 onBlur(舊設計缺口:story Select 只接
+  //   onChange→commit,不選直接 blur → commit 從沒呼叫 → 卡 editing=true,edit chrome 殘留)。
+  // portal-aware:overlay 控件(Select/DatePicker)開的 Radix popper/listbox 是 portaled 出子樹,
+  //   焦點在其中時**不誤結算**(dropdown 操作中);真正離開(都不在 edit 子樹 + 不在本 edit 的 overlay)才 commit。
+  // rAF 延一拍讓焦點落定(Radix 關 popover 時焦點先回 trigger,避免 blur 瞬間誤判)。
+  const handleEditBlur = React.useCallback((e: React.FocusEvent<HTMLDivElement>) => {
+    const wrapper = e.currentTarget
+    requestAnimationFrame(() => {
+      if (finalizedRef.current) return
+      const active = document.activeElement
+      if (active && wrapper.contains(active)) return // 仍在 edit 子樹(如 trigger)
+      // 焦點在本 edit 開的 Radix overlay 內 → dropdown 操作中,不結算
+      if (active && active.closest('[data-radix-popper-content-wrapper],[data-radix-select-viewport],[role="listbox"],[role="dialog"]')) return
+      commit(false) // blur 離開 → 回 view(滑鼠路徑不搶焦)
+    })
+  }, [commit])
+
+  // 鍵盤結算後把 focus 送回 view 按鈕(commit(true)/cancel);滑鼠 blur(commit(false))刻意不送回——
+  //   對齊 inline-edit.spec.md「退出 edit 態(focus 分流)」:鍵盤結算焦點回 view 按鈕 + 藍框、
+  //   滑鼠 blur 回純 view 不搶焦。focus-visible 保證只有鍵盤路徑顯藍框。
   React.useEffect(() => {
     if (!editing && returnFocusRef.current) {
       returnFocusRef.current = false
@@ -185,95 +210,153 @@ function InlineEditImpl<T = string>(
     }
   }, [editing])
 
+  // ── Pointerdown-outside exit(2026-07-17,blur 殘留 root cause 真修)──────────────
+  // focusout 不夠:overlay 控件(Select)點外面關 popover 時 Radix 把焦點送回 trigger(在 edit 子樹內)
+  //   → onBlur 不觸發 → 卡 editing。改用 document-level pointerdown-outside 偵測(對齊 Radix
+  //   DismissableLayer onPointerDownOutside https://www.radix-ui.com/primitives/docs/utilities/dismissable-layer
+  //   + Atlassian inline-edit click-outside 退出
+  //   https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/inline-edit.tsx):
+  //   editing 時點在 edit 子樹外且不在本 edit popover 內的 pointerdown → commit 回 view。
+  //   保證任何控件(含 overlay)點外面都回 display,不靠 consumer 在 renderEdit 自接。
+  React.useEffect(() => {
+    if (!editing) return
+    const onPointerDown = (e: PointerEvent) => {
+      if (finalizedRef.current) return
+      const target = e.target as Element | null
+      if (!target) return
+      const box = editContainerRef.current
+      if (box && box.contains(target)) return // 點在 edit 子樹內(trigger 等)
+      // 點在本 edit 開的 Radix overlay 內(popper / listbox / dialog)→ dropdown 操作中,不結算
+      if (target.closest('[data-radix-popper-content-wrapper],[data-radix-select-viewport],[role="listbox"],[role="dialog"]')) return
+      commit(false)
+    }
+    document.addEventListener('pointerdown', onPointerDown, true)
+    return () => document.removeEventListener('pointerdown', onPointerDown, true)
+  }, [editing, commit])
+
   const isEmpty =
     value == null || (value as unknown) === '' || (Array.isArray(value) && value.length === 0)
   const Tag = as as React.ElementType
-  // 外框(read/edit 兩態共用同一幾何 → 保證「底色範圍 = 輸入框範圍」逐 pixel 一致):
-  //   -mx-[--field-px] 左右各外擴 field-px;w-[calc(100% + 2*--field-px)] 對稱補回 → 兩側等寬填滿。
-  const rootClass = cn('-mx-[var(--field-px)] w-[calc(100%_+_2_*_var(--field-px))]', className)
+
+  // 對齊盒(orientation-aware,Model A;2026-07-17 移除 fieldCtx gate — root cause 修):
+  //   vertical(預設,含 standalone)→ `-mx-field-px` + `w-calc` 把整塊拉到欄左緣(值貼 label 左緣;
+  //     view 委派控件在 `surface='inline-edit'` 下 px 統一 field-px → 被 -mx 精準抵消 → 落 x=0 對齊 label)。
+  //   horizontal → 不用 -mx(純 `w-full`,值內縮 px = 對齊 sibling 控件)。
+  //   ⚠️ **移除舊 `fieldCtx &&` gate(root cause)**:standalone 預設 orientation='vertical'(:131),舊 gate 讓
+  //     standalone 掉到 `w-full` 無 -mx → 內容內縮 field-px 不對齊 label(圖一/圖二 bug)。spec Model A
+  //     (field-controls.spec.md:71「orientation-aware -mx / vertical 貼 label」)只依 orientation、不依 fieldCtx。
+  //     -mx bleed field-px 到容器 padding = 刻意(hover/edit 才顯真實邊界)→ consumer 放 ≥field-px padding 容器
+  //     (detail panel / card;stories 容器 layout-space-loose 16px > field-px 12px 天然吸收)。
+  const alignBleed =
+    orientation === 'vertical'
+      ? '-mx-[var(--field-px)] w-[calc(100%_+_2_*_var(--field-px))]'
+      : 'w-full min-w-0'
 
   if (editing) {
     const editProps: InlineEditRenderProps<T> = {
       value: draft,
       onChange: setDraftValue,
-      commit,
+      commit: () => commit(true),
       cancel,
       autoFocus: true,
       size,
       'aria-label': label,
     }
     // 預設 edit 控件:multiline → Textarea(Enter=換行、Cmd/Ctrl+Enter/blur 提交);否則 Input。
-    // 兩者 Enter/Esc 結算都走 makeEditSettleKeyHandler(含 IME guard)。string-only 預設路徑;
-    // 非 string 值必傳 renderEdit。
+    // 兩者皆 mode="edit"(edit 態 = 真正的 edit-mode Field 控件),Enter/Esc 結算走 makeEditSettleKeyHandler(含 IME guard)。
+    // string-only 預設路徑;非 string 值必傳 renderEdit。
     const defaultEditNode = multiline ? (
       <Textarea
         autoFocus
+        mode="edit"
         value={draft as unknown as string}
         size={size}
         aria-label={label}
         onChange={(e) => setDraftValue(e.target.value as unknown as T)}
-        onBlur={commit}
-        // 多行:plain Enter=換行、Esc=cancel、Cmd/Ctrl+Enter=commit —— 全走
-        // makeEditSettleKeyHandler SSOT(含 IME guard + Cmd/Ctrl+Enter),不再手刻 capture。
-        onKeyDown={makeEditSettleKeyHandler({ onCommit: commit, onCancel: cancel, commitOnEnter: false })}
+        onBlur={() => commit(false)}
+        // 多行:plain Enter=換行、Esc=cancel、Cmd/Ctrl+Enter=commit —— 全走 makeEditSettleKeyHandler SSOT。
+        onKeyDown={makeEditSettleKeyHandler({ onCommit: () => commit(true), onCancel: cancel, commitOnEnter: false })}
       />
     ) : (
       <Input
         autoFocus
+        mode="edit"
         value={draft as unknown as string}
         size={size}
         aria-label={label}
         onChange={(e) => setDraftValue(e.target.value as unknown as T)}
-        onBlur={commit}
-        onKeyDown={makeEditSettleKeyHandler({ onCommit: commit, onCancel: cancel })}
+        onBlur={() => commit(false)}
+        onKeyDown={makeEditSettleKeyHandler({ onCommit: () => commit(true), onCancel: cancel })}
       />
     )
     const editNode = renderEdit ? renderEdit(editProps) : defaultEditNode
     return (
-      <div ref={ref} data-editing={editing} className={rootClass}>
+      // exit SSOT 雙保險:onBlur(focusout,tab-out / 非 overlay 控件)+ document pointerdown-outside(overlay
+      //   點外面 Radix 送焦回 trigger 時 focusout 不觸發之補位)。任何 edit 控件離開 → 回 view。
+      // edit 態**不套** surface='inline-edit'(完全繼承原 field,含 tagPadding — Jira 式,user 2026-07-17 拍板)。
+      <div ref={setEditContainerRef} data-editing className={cn(alignBleed, className)} onBlur={handleEditBlur}>
         {editNode}
       </div>
     )
   }
 
+  // view 態:外框只承載對齊盒 + (editable 時) hover bg + 鍵盤 focus 藍框;幾何由內容(委派控件 view / fieldViewGeometry)提供。
+  const viewNode = renderRead ? (
+    // 格式化 view(consumer 傳 <Control mode="view"> 等)。**對齊 SSOT(2026-07-17)**:委派控件的
+    // bare view 一律 0px 左內距(audit 證實 Select/Combobox/DatePicker/TimePicker/PeoplePicker/LinkInput
+    // 預設 view 皆裸 span/Tag),故 InlineEdit 用**與純值路徑同一個 `fieldViewGeometry(field-px + min-h +
+    // py)`** 包住 renderRead → 委派控件 view 左 px 統一 field-px、高度統一 field-height → 固定
+    // `-mx-field-px` 精準抵消 → tag/avatar/值左緣落 label x=0。不碰任何控件 tagPadding(bare view 本就不用)。
+    // surface='inline-edit' 保留為 per-control 逃生訊號(若某控件 bare view 有內部 inset 破壞對齊,該控件可
+    // 讀 surface 自抑;目前全控件 bare view=0px 不需)。
+    <FieldSurfaceProvider surface="inline-edit">
+      <div className={fieldViewGeometry(size, multiline)}>{renderRead(value)}</div>
+    </FieldSurfaceProvider>
+  ) : (
+    <Tag
+      data-empty={isEmpty}
+      className={cn(
+        // 純值/標題共用 view 幾何 SSOT(px-field-px + min-h-field + 單行 items-center / 多行 items-start py-2)
+        fieldViewGeometry(size, multiline),
+        // view 態 typography 預設消費 Field view SSOT(sm/md→text-body,lg→text-body-lg)——
+        // plain 用法 view 字級 = edit <Input>(text-body)= <Input mode="view"> 字級,三者一致零跳字。
+        fieldDisplayTextClass(size),
+        // 多行:保留換行(pre-wrap)+ 長字斷行 —— view 忠實呈現 Textarea 內容(Jira description 類)。
+        multiline && 'whitespace-pre-wrap break-words',
+        readClassName,
+        isEmpty && 'text-fg-muted',
+      )}
+    >
+      {isEmpty ? placeholder : String(value)}
+    </Tag>
+  )
+
   return (
     <div
       ref={ref}
-      data-editing={editing}
-      // 外框(rootClass 幾何)+ read chrome(inlineEditReadStyles:border 預留 / px / min-h / hover 底色 / focus 藍框)
-      className={cn(rootClass, inlineEditReadStyles({ size, multiline }))}
+      data-editing={false}
+      data-editable={editable || undefined}
+      className={cn(
+        'relative flex min-w-0 rounded-md border border-transparent transition-colors duration-150',
+        alignBleed,
+        // editable 才有 hover 底色 + 鍵盤 focus 藍框(Field focus 語言,非 Button ring);
+        //   editable=false = 純 view 鎖定,無入口、無藍框、不灰化。
+        editable && 'hover:bg-neutral-hover [&:has(button:focus-visible)]:border-primary',
+        className,
+      )}
     >
-      {renderRead ? (
-        // 格式化 read view(consumer 傳 <Select mode="display"> 等)。invisible Pressable 疊其上供點擊進 edit。
-        <div className="w-full min-w-0">{renderRead(value)}</div>
-      ) : (
-        <Tag
-          data-empty={isEmpty}
-          className={cn(
-            'w-full min-w-0',
-            // read 態 typography 預設消費 Field display SSOT(sm/md→text-body,lg→text-body-lg)——
-            // plain 用法 read 字級 = edit <Input>(text-body)= <Input mode="display"> 字級,三者一致零跳字。
-            fieldDisplayTextClass(size),
-            // 多行:保留換行(pre-wrap)+ 長字斷行 —— read 忠實呈現 Textarea 內容(Jira description 類),
-            // 對齊 Textarea mode="display" 的 `whitespace-pre-wrap break-words`。
-            multiline && 'whitespace-pre-wrap break-words',
-            readClassName,
-            isEmpty && 'text-fg-muted',
-          )}
-        >
-          {isEmpty ? placeholder : String(value)}
-        </Tag>
+      {viewNode}
+      {/* 隱形 Pressable(僅 editable):提供 click + 鍵盤 Tab focus + Enter/Space 進 edit;透明疊於內容上。
+          hover 底色 + focus 藍框由外層 div 承載(Field focus 語言),故本 button 只需 outline-none 消瀏覽器預設外框。 */}
+      {editable && (
+        <button
+          ref={readButtonRef}
+          type="button"
+          aria-label={label ? `編輯 ${label}` : '編輯'}
+          onClick={enterEdit}
+          className="absolute inset-0 cursor-text rounded-md focus-visible:outline-none"
+        />
       )}
-      {/* 隱形 Pressable:提供 click + 鍵盤 Tab focus + Enter/Space 進 edit;透明疊於內容上。
-          hover 底色 + focus 藍框(border-primary)由外層 div 承載(Field focus 語言,非 ring),
-          故本 button 只需 outline-none 消除瀏覽器預設外框。 */}
-      <button
-        ref={readButtonRef}
-        type="button"
-        aria-label={label ? `編輯 ${label}` : '編輯'}
-        onClick={enterEdit}
-        className="absolute inset-0 cursor-text rounded-md focus-visible:outline-none"
-      />
     </div>
   )
 }
@@ -281,7 +364,10 @@ function InlineEditImpl<T = string>(
 // 泛型 forwardRef:forwardRef 不原生支援泛型,以 cast 還原公開型別(標準 workaround)。
 const InlineEdit = React.forwardRef(InlineEditImpl) as (<T = string>(
   props: InlineEditProps<T> & { ref?: React.Ref<HTMLDivElement> },
-) => React.ReactElement) & { displayName?: string }
+) => React.ReactElement) & { displayName?: string; fieldPreferredSize?: FieldSize }
 InlineEdit.displayName = 'InlineEdit'
+// 靜態偏好尺寸:外層 `<Field>` render 時讀 `child.type.fieldPreferredSize` → Field.size 未顯式指定時收 sm
+//   (對齊 detectControlLayout 讀 fieldLayout 的機制;InlineEdit view 態無邊框,md 過大會讓版面鬆散)。
+InlineEdit.fieldPreferredSize = 'sm'
 
 export { InlineEdit }

package/src/components/Input/input.anatomy.stories.tsx

@@ -13,12 +13,12 @@ export default meta
    Types & Data
    ═══════════════════════════════════════════════════════════════════════════ */
 
-type ModeKey = 'edit' | 'display' | 'readonly' | 'disabled'
+type ModeKey = 'edit' | 'view' | 'readonly' | 'disabled'
 type StateKey = 'default' | 'hover' | 'focus' | 'error' | 'disabled'
 type SizeKey = 'sm' | 'md' | 'lg'
 type ColorSpec = { bg: string; text: string; border: string; placeholder: string }
 
-const MODES: ModeKey[] = ['edit', 'display', 'readonly', 'disabled']
+const MODES: ModeKey[] = ['edit', 'view', 'readonly', 'disabled']
 const EDIT_STATES: StateKey[] = ['default', 'hover', 'focus', 'error', 'disabled']
 const SIZES: SizeKey[] = ['sm', 'md', 'lg']
 
@@ -30,7 +30,7 @@ const COLOR_MAP: Record<ModeKey, Partial<Record<StateKey, ColorSpec>>> = {
     error:    { bg: '--surface',      text: '--foreground',  border: '--error',         placeholder: '--fg-muted' },
     disabled: { bg: '--bg-disabled',  text: '--fg-disabled', border: 'transparent',     placeholder: '--fg-disabled' },
   },
-  display: {
+  view: {
     default:  { bg: 'transparent',    text: '--foreground',  border: 'transparent',     placeholder: '--fg-muted' },
   },
   readonly: {
@@ -58,7 +58,7 @@ const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
 
 const MODE_DESC: Record<ModeKey, string> = {
   edit:     '表單可編輯欄位 — bg-surface + border + hover/focus 回饋',
-  display:  '純展示資料 — 無 chrome（transparent + !px-0 !py-0 零內距，field-wrapper.tsx Path Ⅰ）+ 文字正常色，空值顯示半形 -（hyphen，同 value 前景色）',
+  view:     '純展示值（非表單）— edit 幾何減 chrome（transparent bg/border，**保留 px-field-px 內距與高度**，Model A round16）+ 文字正常色，空值顯示半形 -（hyphen，同 value 前景色）。用在 cell / InlineEdit / 詳情',
   readonly: '不可編輯但可見 — bg-readonly(neutral-2) + 無邊框 + 文字正常色',
   disabled: '被停用的欄位 — bg-disabled(neutral-2) + 無邊框 + 文字灰化',
 }
@@ -211,9 +211,9 @@ export const Overview = {
           {MODES.map((m) => (
             <div key={m} className="flex items-center gap-4">
               <div className="w-64 shrink-0">
-                {/* display + readonly 讀 controlled value:兩者「空值」皆走 <span> 顯 '-'(input.tsx:121),
+                {/* view + readonly 讀 controlled value:兩者「空值」皆走 <span> 顯 '-'(input.tsx:121),
                     demo 要展示有值狀態故傳 value;edit / disabled 用 defaultValue 保持 uncontrolled */}
-                {(m === 'display' || m === 'readonly') ? (
+                {(m === 'view' || m === 'readonly') ? (
                   <Input mode={m} value="Wireless Bluetooth Headphones" size="md" />
                 ) : (
                   <Input mode={m} defaultValue="Wireless Bluetooth Headphones" size="md" />
@@ -242,8 +242,8 @@ export const Overview = {
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
               {[
-                ['mode', "'edit' | 'display' | 'readonly' | 'disabled'", "'edit'", 'mode 未顯式指定時依序推導：有效 disabled（prop 或 <Field disabled>）→ fieldCtx.mode → native readOnly → edit；顯式 mode prop 永遠最優先（field-context.ts useResolvedFieldMode）'],
-                ['variant', "'default'", "'default'", '視覺 chrome（正交於 mode；公開型別僅 default，2026-07-14 收窄）；naked = 無 chrome，host cell 提供 border/focus（@internal cell-as-input）；bare 2026-07-09 退役'],
+                ['mode', "'edit' | 'view' | 'readonly' | 'disabled'", "'edit'", 'mode 未顯式指定時依序推導：有效 disabled（prop 或 <Field disabled>）→ fieldCtx.mode → native readOnly → edit；顯式 mode prop 永遠最優先（field-context.ts useResolvedFieldMode）'],
+                ['variant', "'default'", "'default'", '視覺 chrome（正交於 mode；公開型別僅 default，2026-07-14 收窄）；naked = cell-as-input substrate（@internal）：edit×naked 自畫 border-based state machine（border → hover → focus-within primary → error 紅框），view×naked 才由 host cell 提供視覺邊框；bare 2026-07-09 退役'],
                 ['error', 'boolean', 'false', '紅色邊框僅 edit 模式生效；aria-invalid 不分 mode（readonly / disabled 渲染的 input 同樣帶）'],
                 ['size', "'sm' | 'md' | 'lg'", "'md'", '高度與字體，與 Button 共用 field-height token'],
                 ['startIcon', 'LucideIcon', '—', '左側靜態 icon，fg-muted，pointer-events-none'],
@@ -334,8 +334,8 @@ const InspectorInner = () => {
               error={error}
               startIcon={hasStartIcon ? Search : undefined}
               endAction={hasEndAction && isEdit ? { icon: X, label: '清除', onClick: () => {} } : undefined}
-              // display mode 讀 value 渲染 <span>;其餘 mode 用 defaultValue 保持 uncontrolled
-              {...(mode === 'display'
+              // view mode 讀 value 渲染 <span>;其餘 mode 用 defaultValue 保持 uncontrolled
+              {...(mode === 'view'
                 ? { value: 'Wireless Bluetooth Headphones' }
                 : { defaultValue: 'Wireless Bluetooth Headphones' })}
               key={mode}
@@ -361,7 +361,7 @@ const InspectorInner = () => {
             </div>
             <div className="flex items-center">
               <div className="flex items-center rounded-md overflow-hidden" style={{ height: 52, outline: `2px solid ${Z.dim.text}22` }}>
-                <BpZone w={44} color={Z.pad} label={mode === 'display' ? '!px-0' : s.pxToken} sub={mode === 'display' ? '0px' : `${s.px}px`} />
+                <BpZone w={44} color={Z.pad} label={s.pxToken} sub={`${s.px}px`} />
                 {hasStartIcon && (
                   <>
                     <BpZone w={44} color={Z.icon} label={`${s.icon}px`} sub="icon" />
@@ -375,7 +375,7 @@ const InspectorInner = () => {
                     <BpZone w={44} color={Z.action} label={`${s.icon}px`} sub="action" />
                   </>
                 )}
-                <BpZone w={44} color={Z.pad} label={mode === 'display' ? '!px-0' : s.pxToken} sub={mode === 'display' ? '0px' : `${s.px}px`} />
+                <BpZone w={44} color={Z.pad} label={s.pxToken} sub={`${s.px}px`} />
               </div>
               <div className="ml-3 flex items-center" style={{ height: 52 }}>
                 <svg width="10" height="52" className="shrink-0">
@@ -426,7 +426,7 @@ const InspectorInner = () => {
           <div className="px-4 py-1">
             <div className="py-2 border-b border-divider"><span className="text-[10px] font-semibold text-fg-muted uppercase tracking-wider">Layout</span></div>
             <PropRow label="高度" dot={Z.dim.text}><TkVal token={s.heightToken} value={s.height} /></PropRow>
-            <PropRow label="左右內距" dot={Z.pad.text}><TkVal token={mode === 'display' ? '!px-0 !py-0' : s.pxToken} value={mode === 'display' ? '0px（零 chrome）' : `${s.px}px`} /></PropRow>
+            <PropRow label="左右內距" dot={Z.pad.text}><TkVal token={s.pxToken} value={`${s.px}px（view 保留 = edit 幾何減 chrome）`} /></PropRow>
             <PropRow label="元素間距" dot={Z.gap.text}><TkVal token={s.gapToken} value={`${s.gap}px`} /></PropRow>
             {hasStartIcon && (
               <PropRow label="Icon 尺寸" dot={Z.icon.text}>{s.icon}px</PropRow>
@@ -452,7 +452,7 @@ const InspectorInner = () => {
             <div className="py-2 border-b border-divider"><span className="text-[10px] font-semibold text-fg-muted uppercase tracking-wider">Style</span></div>
             <PropRow label="Radius"><TkVal token="rounded-md" value="4px" /></PropRow>
             <PropRow label="Border"><TkVal token="border" value="1px solid" /></PropRow>
-            <PropRow label="Focus"><TkVal token="border-primary" value="1px — 無 ring" /></PropRow>
+            <PropRow label="Focus"><TkVal token="border-primary" value="1px — 無 ring（readonly 例外:ring-2 ring-ring,WCAG 2.4.7）" /></PropRow>
             <PropRow label="Transition"><TkVal token="transition-colors" value="150ms" /></PropRow>
           </div>
         </div>
@@ -675,7 +675,7 @@ export const StateBehavior = {
 
         {/* Focus behavior */}
         <div className="flex flex-col gap-4">
-          <span className="text-caption font-medium text-fg-secondary">Focus — border-primary（1px），無 ring</span>
+          <span className="text-caption font-medium text-fg-secondary">Focus — border-primary（1px），無 ring（readonly 例外:ring-2 ring-ring focus 指示,WCAG 2.4.7）</span>
           <div className="flex flex-col gap-2 max-w-sm">
             <span className="text-[11px] text-fg-muted">文字輸入永遠 focus-visible（瀏覽器規範），click 和 Tab 觸發相同效果。點擊下方 input 或用 Tab 切換觀察。</span>
             <Input placeholder="點擊或 Tab 觀察 focus 邊框" />