@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

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

@@ -0,0 +1,455 @@
+// ── 消費的 SSOT ──
+// - 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(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 回饋)
+// - 世界級對照(泛型 readView/editView 就地編輯 + read 態底色 tint + 隱形 Pressable):
+//   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/
+//
+// ── 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 { useFieldContext, useResolvedFieldSize, useRegisterFieldPreferredSize, 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'
+import { useTruncated } from '@/design-system/hooks/use-truncated'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/** renderEdit 回呼收到的受控介面 —— consumer 換任意 Field 控件(Textarea / Select / DatePicker …)接線用 */
+export interface InlineEditRenderProps<T = string> {
+  /** 目前編輯中的草稿值(內部管理,非已 commit 的 value) */
+  value: T
+  /** 草稿變更 */
+  onChange: (next: T) => void
+  /** 提交草稿 → onCommit(next) + 回 view 態 */
+  commit: () => void
+  /** 放棄草稿 → 回 view 態不 commit */
+  cancel: () => void
+  /** 進 edit 態時自動 focus 控件 */
+  autoFocus: boolean
+  /** 尺寸(cascade 給控件,與 view 態高度對齊) */
+  size: FieldSize
+  /** 控件無障礙標籤(= label prop) */
+  'aria-label'?: string
+}
+
+type ReadTag = 'span' | 'p' | 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+
+export interface InlineEditProps<T = string> {
+  /** 已提交的欄位值(view 態顯示;edit 進入時作草稿初值)。泛型:string / number / string[] / PersonValue 等 */
+  value: T
+  /** 提交回呼 —— blur / Enter 且草稿有變更時觸發 */
+  onCommit: (next: T) => void
+  /**
+   * 自訂 edit 態控件(換 Textarea / Select / DatePicker 等 Field 控件,必用 `mode="edit"`)。
+   * 不傳則預設:multiline → `<Textarea mode="edit">`,否則 `<Input mode="edit">`(僅 T=string 時預設有效;非 string 值必傳此 prop)。
+   */
+  renderEdit?: (props: InlineEditRenderProps<T>) => React.ReactNode
+  /**
+   * 自訂 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 類):view 態換行 + 預設 edit 態用 `<Textarea>`,Enter=換行、Cmd/Ctrl+Enter 或 blur 提交 */
+  multiline?: boolean
+  /**
+   * 多行 edit 態的高度上限(行數)。預設無上限 —— 高度隨內容,與 view 態同源(= DataTable cell 語意)。
+   * 設定後超過行數改為捲動。僅在 `multiline` 時有意義。
+   */
+  editMaxRows?: number
+  /**
+   * 是否可編輯(預設 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
+  /** 空值時 view 態顯示的提示文字(fg-muted) */
+  placeholder?: string
+  /** 尺寸 —— view 態最小高度 + 預設 Input 尺寸(不傳則經 useResolvedFieldSize 接 Field size cascade,standalone fallback sm) */
+  size?: FieldSize
+  /** view 態語意標籤(標題場景傳 'h1'/'h2' 維持文件大綱;預設 'span') */
+  as?: ReadTag
+  /** view 態文字樣式(如標題 `text-h4 font-bold`) */
+  readClassName?: string
+  /** 外層容器 className */
+  className?: string
+}
+
+/**
+ * InlineEdit — 就地編輯 primitive(view ↔ edit 二態,泛型 <T>)
+ *
+ * 互動模型 world-class 對照見檔頭「消費的 SSOT」+ inline-edit.spec.md benchmark 表:
+ * - **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 鎖定語意)
+ *
+ * view 態用隱形 Pressable(絕對定位 `<button>` 疊於內容上)—— 讓 `as="h1"` 等標題標籤保留文件大綱
+ * a11y,同時提供鍵盤 focus + Enter 進 edit(HTML 內容模型不允許 heading 巢狀於 button,故分離)。
+ */
+function InlineEditImpl<T = string>(
+  {
+    value,
+    onCommit,
+    renderEdit,
+    renderRead,
+    multiline = false,
+    editMaxRows,
+    editable = true,
+    label,
+    placeholder,
+    size: sizeProp,
+    as = 'span',
+    readClassName,
+    className,
+  }: InlineEditProps<T>,
+  ref: React.Ref<HTMLDivElement>,
+) {
+  // size:接 fieldCtx.size cascade,fallback sm。Field 只有在 consumer 顯式指定或已解析出偏好時
+  //   才壓過此 fallback(sizeExplicit),因此包一層 wrapper 也不會靜默退回 md。
+  const size = useResolvedFieldSize(sizeProp, 'sm')
+  // 同時向外層 Field 註冊偏好,讓 Field 的控件槽高度跟上(靜態 fieldPreferredSize 被 wrapper 遮蔽時的補位)。
+  useRegisterFieldPreferredSize('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 送回 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
+    setDraft(next)
+  }, [])
+
+  const enterEdit = React.useCallback(() => {
+    finalizedRef.current = false
+    setDraftValue(value)
+    setEditing(true)
+  }, [value, setDraftValue])
+
+  // 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 // Esc = 鍵盤路徑,焦點回 view 按鈕
+    setEditing(false)
+  }, [])
+
+  // ── 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
+      readButtonRef.current?.focus()
+    }
+  }, [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
+
+  // 單行純值 view 的截斷 tooltip:量測內層值 span,但 **trigger = 整個 view 容器**。
+  // 不能用 <TruncatedText>(trigger=值 span 本身):view 上疊著透明 Pressable(click-to-edit
+  // 入口,absolute inset-0),所有 hover 都被按鈕吞掉,值 span 永遠收不到 pointerenter →
+  // tooltip 永不開(2026-07-28 user 實測抓到)。truncated-text.spec 對「trigger 需自控」場景
+  // 的指定解 = 直接消費 public useTruncated 自組;DataTable cell 無疊層所以能用 primitive。
+  const singleLinePlainView = !renderRead && !multiline
+  const { ref: truncationRef, isTruncated } = useTruncated<HTMLSpanElement>({
+    deps: [singleLinePlainView && !isEmpty ? String(value) : ''],
+  })
+  const plainTruncationActive = singleLinePlainView && !isEmpty && isTruncated
+
+  // 委派 view(renderRead)同規則(tooltip.spec.md「截斷文字 → tooltip,截斷才顯」):委派控件
+  // 自帶的截斷 tooltip(Input <TruncatedText> / Tag)trigger 在內層,editable 時同樣被透明
+  // Pressable 吞掉 hover → 永不開,故外層容器 Tooltip 一併服務委派路徑。量測 = use-truncated
+  // options.measure 自訂策略(檔頭明載 Tag「observe root、量測內層」即同款開口):走訪 wrapper
+  // 子樹,任一 `.truncate` 後代溢出即視為截斷(委派控件截斷元素皆帶 truncate class:Tag 內層
+  // span / TruncatedText span / Select view span)。editable=false 不渲染 Pressable → 控件自身
+  // tooltip 可達,外層讓位避免雙重顯示。
+  const delegatedView = !!renderRead
+  const { ref: delegatedViewRef, isTruncated: delegatedTruncated } = useTruncated<HTMLDivElement>({
+    measure: (el) =>
+      Array.from(el.querySelectorAll<HTMLElement>('.truncate')).some(
+        (node) => node.scrollWidth > node.clientWidth,
+      ),
+    deps: [delegatedView && editable && !isEmpty ? value : null],
+  })
+  const delegatedTruncationActive = delegatedView && editable && !isEmpty && delegatedTruncated
+  const truncationTooltipActive = plainTruncationActive || delegatedTruncationActive
+
+  // 對齊盒(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(true),
+      cancel,
+      autoFocus: true,
+      size,
+      'aria-label': label,
+    }
+    // 預設 edit 控件:multiline → Textarea(Enter=換行、Cmd/Ctrl+Enter/blur 提交);否則 Input。
+    // 兩者皆 mode="edit"(edit 態 = 真正的 edit-mode Field 控件),Enter/Esc 結算走 makeEditSettleKeyHandler(含 IME guard)。
+    // string-only 預設路徑;非 string 值必傳 renderEdit。
+    const defaultEditNode = multiline ? (
+      <Textarea
+        autoFocus
+        mode="edit"
+        // view 態高度由內容決定,edit 態必須同源,否則 read↔edit 之間跳高(DataTable cell 早就是
+        // 內容驅動,standalone InlineEdit 原本卡在 rows=3)。consumer 要上限就傳 editMaxRows。
+        autoSize={editMaxRows === undefined ? true : { maxRows: editMaxRows }}
+        value={draft as unknown as string}
+        size={size}
+        aria-label={label}
+        onChange={(e) => setDraftValue(e.target.value as unknown as T)}
+        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(false)}
+        onKeyDown={makeEditSettleKeyHandler({ onCommit: () => commit(true), onCancel: cancel })}
+      />
+    )
+    const editNode = renderEdit ? renderEdit(editProps) : defaultEditNode
+    return (
+      // 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">
+      {/* delegatedViewRef = 委派路徑截斷量測根(walk `.truncate` 後代;見上方 useTruncated 註解) */}
+      <div ref={delegatedViewRef} 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 || multiline
+        ? (isEmpty ? placeholder : String(value))
+        // 單行 view 恆一行:溢出改 ellipsis(tooltip.spec.md「截斷文字 → tooltip」);
+        // tooltip 掛在外層 view 容器(見 truncationRef 註解——隱形 Pressable 吞 hover)。
+        : <span ref={truncationRef} className="truncate min-w-0">{String(value)}</span>}
+    </Tag>
+  )
+
+  return (
+    // 截斷 tooltip:trigger = 整個 view 容器(隱形 Pressable 吞掉內層 hover,故不能掛在值 span);
+    // 純值路徑量內層值 span、委派路徑量 wrapper 子樹(見上方兩段 useTruncated 註解);
+    // 恆 wrap 保 DOM 生命週期穩定(truncated-text 檔頭 always-wrap 教訓),未截斷時 open={false} 靜默。
+    <Tooltip open={truncationTooltipActive ? undefined : false}>
+      <TooltipTrigger asChild>
+        <div
+          ref={ref}
+          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,
+          )}
+        >
+          {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"
+            />
+          )}
+        </div>
+      </TooltipTrigger>
+      <TooltipContent>
+        {delegatedTruncationActive
+          ? // 委派路徑內容 = wrapper 子樹當下 DOM 的 textContent(完整格式化文字;
+            // 非 string T 不可 String(value) —— 如 string[] / PersonValue)
+            delegatedViewRef.current?.textContent
+          : plainTruncationActive
+            ? String(value)
+            : null}
+      </TooltipContent>
+    </Tooltip>
+  )
+}
+
+// 泛型 forwardRef:forwardRef 不原生支援泛型,以 cast 還原公開型別(標準 workaround)。
+const InlineEdit = React.forwardRef(InlineEditImpl) as (<T = string>(
+  props: InlineEditProps<T> & { ref?: React.Ref<HTMLDivElement> },
+) => 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'
+
+// Story auto-compile metadata — canonical migration(2026-08-01)
+// Geometry and size belong to Field controls; InlineEdit owns only the
+// view-to-edit orchestration and its read-view interaction affordances.
+export const inlineEditMeta = {
+  component: 'InlineEdit',
+  family: 'composite',
+  variants: {},
+  sizes: {},
+  states: ['default', 'hover', 'focus-visible', 'editing', 'readonly'],
+  tokens: {
+    bg: ['bg-neutral-hover'],
+    fg: ['text-fg-muted'],
+    border: ['border-transparent', 'border-primary'],
+    ring: [],
+  },
+  defaultVariant: undefined,
+  defaultSize: undefined,
+} as const
+
+export { InlineEdit }

package/src/components/Input/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 './input'