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

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

@@ -0,0 +1,142 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — 本檔 brand 引用(Jira/Linear/Notion)為真實業務場景示意(mindset #4),非 URL-citable 的 DS 行為 benchmark claim。
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { InlineEdit } from './inline-edit'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+import { Input } from '@/design-system/components/Input/input'
+
+/**
+ * InlineEdit 設計原則(principles)—— 何時用 / 何時不用 / 近親分界 / 內容準則。
+ */
+const meta: Meta<typeof InlineEdit> = {
+  title: 'Design System/Components/InlineEdit/設計原則',
+  component: InlineEdit,
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof InlineEdit>
+
+function Card({ tone, title, children }: { tone: 'do' | 'dont' | 'neutral'; title: string; children: React.ReactNode }) {
+  const ring = tone === 'do' ? 'border-success' : tone === 'dont' ? 'border-error' : 'border-border'
+  const tag = tone === 'do' ? '✓ 適用' : tone === 'dont' ? '✕ 不適用' : '—'
+  const tagColor = tone === 'do' ? 'text-success' : tone === 'dont' ? 'text-error' : 'text-fg-muted'
+  return (
+    <div className={`rounded-lg border ${ring} bg-surface p-[var(--layout-space-loose)]`}>
+      <p className={`mb-1 text-caption font-semibold ${tagColor}`}>{tag}</p>
+      <p className="mb-2 text-body font-medium text-foreground">{title}</p>
+      <div className="text-body text-fg-secondary">{children}</div>
+    </div>
+  )
+}
+function Stateful({ value: initial, ...props }: Omit<React.ComponentProps<typeof InlineEdit>, 'onCommit'>) {
+  const [value, setValue] = React.useState(initial)
+  return <InlineEdit {...props} value={value} onCommit={setValue} />
+}
+
+export const WhenToUse: Story = {
+  name: '何時用',
+  render: () => (
+    <div className="grid max-w-[860px] grid-cols-2 gap-4">
+      <Card tone="do" title="詳情面板的可編欄位">
+        Jira / Linear issue 詳情、Notion property —— 值平常是純內容,原地點擊即可改,不跳表單。
+        <div className="mt-3"><Stateful value="Fix flaky checkout e2e test" label="標題" /></div>
+      </Card>
+      <Card tone="do" title="標題型就地編輯">
+        頁面 / 文件標題 <code>as="h1"</code>,保留文件大綱,同時可點擊改名。
+        <div className="mt-3"><Stateful as="h2" value="Q3 產品路線圖" readClassName="text-h5 font-bold" label="文件標題" /></div>
+      </Card>
+      <Card tone="do" title="唯讀值同場並列(editable=false)">
+        系統產生值(訂單編號、建立時間)與可編欄位並列 —— 用 <code>editable=false</code>,視覺一致但無編輯入口、不灰化。
+        <div className="mt-3"><Stateful value="PROJ-482" label="編號" editable={false} /></div>
+      </Card>
+      <Card tone="do" title="格式化值就地編輯">
+        狀態 Tag / 日期 / 負責人頭像 —— <code>renderRead</code> 委派控件 view mode,edit 換該控件 edit mode。
+      </Card>
+    </div>
+  ),
+}
+
+export const WhenNotToUse: Story = {
+  name: '何時不用',
+  render: () => (
+    <div className="grid max-w-[860px] grid-cols-2 gap-4">
+      <Card tone="dont" title="整張表單填寫">
+        新增 / 建立流程要一次填多欄 —— 用 <code>&lt;Field&gt; + 控件</code> 明確表單,不用逐欄就地編輯。
+        <div className="mt-3">
+          <Field><FieldLabel>Email</FieldLabel><Input placeholder="you@company.com" /></Field>
+        </div>
+      </Card>
+      <Card tone="dont" title="永久唯讀、不同場可編欄位">
+        純展示頁(唯讀報表)—— 直接用 <code>&lt;Control mode="view"&gt;</code> 或純文字,不需就地編輯的 hover 入口成本。
+      </Card>
+      <Card tone="dont" title="需要即時驗證 / 複雜互動">
+        密碼、需即時錯誤回饋、multi-step 的欄位 —— 用完整 Field + FieldError,不塞進二態就地編輯。
+      </Card>
+      <Card tone="dont" title="條件停用的欄位">
+        「選國家前城市不可填」這種表單條件停用 —— 用 <code>&lt;Field mode="disabled"&gt;</code>,不是 InlineEdit
+        (就地編輯無 disabled 態;鎖定 = editable=false 純 view)。
+      </Card>
+    </div>
+  ),
+}
+
+export const VsControlView: Story = {
+  name: '近親分界:就地編輯 vs 唯讀展示 vs 表單',
+  render: () => (
+    <div className="max-w-[820px]">
+      <table className="w-full">
+        <thead>
+          <tr className="border-b-2 border-border text-left text-caption font-semibold text-fg-muted">
+            <th className="py-2 pr-4">用它</th>
+            <th className="py-2 pr-4">場景</th>
+            <th className="py-2">可編 / 入口</th>
+          </tr>
+        </thead>
+        <tbody className="text-body text-fg-secondary">
+          <tr className="border-b border-divider align-top">
+            <td className="py-2 pr-4 font-medium text-foreground">InlineEdit</td>
+            <td className="py-2 pr-4">詳情面板、可原地改的值</td>
+            <td className="py-2">view↔edit,hover 入口(editable=true)</td>
+          </tr>
+          <tr className="border-b border-divider align-top">
+            <td className="py-2 pr-4 font-medium text-foreground">InlineEdit editable=false</td>
+            <td className="py-2 pr-4">與可編欄位並列的唯讀值(訂單編號)</td>
+            <td className="py-2">純 view,無入口、不灰化</td>
+          </tr>
+          <tr className="border-b border-divider align-top">
+            <td className="py-2 pr-4 font-medium text-foreground">{'<Control mode="view">'}</td>
+            <td className="py-2 pr-4">永久唯讀展示頁的值</td>
+            <td className="py-2">純展示,無互動</td>
+          </tr>
+          <tr className="align-top">
+            <td className="py-2 pr-4 font-medium text-foreground">{'<Field> + 控件'}</td>
+            <td className="py-2 pr-4">表單填寫(一次多欄)</td>
+            <td className="py-2">恆 edit,label + error</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  ),
+}
+
+export const ContentGuidelines: Story = {
+  name: '內容準則',
+  render: () => (
+    <div className="grid max-w-[860px] grid-cols-2 gap-4">
+      <Card tone="do" title="placeholder 用行動語氣">
+        空值提示寫「指派負責人…」「新增說明…」,告訴使用者能做什麼,而非「無」。
+        <div className="mt-3"><Stateful value="" label="負責人" placeholder="指派負責人…" /></div>
+      </Card>
+      <Card tone="do" title="label 傳人類可讀名稱">
+        <code>label</code> 組出 aria-label「編輯 負責人」—— 傳欄位真名,別傳代號。
+      </Card>
+      <Card tone="dont" title="別把格式化 Tag 自刻">
+        狀態值要顯示 Tag,<code>renderRead</code> 必須渲染 <code>&lt;Select mode="view" display="tag"&gt;</code> ——
+        自己拼 <code>&lt;Tag&gt;</code> 會與 edit 態格式漂移。
+      </Card>
+      <Card tone="neutral" title="多行用 multiline">
+        Jira description 類長文字傳 <code>multiline</code> —— view 保留換行、edit 換 Textarea,上下 padding 一致。
+      </Card>
+    </div>
+  ),
+}

package/src/components/InlineEdit/inline-edit.spec.md

@@ -0,0 +1,186 @@
+---
+component: InlineEdit
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+benchmark:
+  - Atlassian inline-edit read-view: https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx
+  - PatternFly inline-edit: https://www.patternfly.org/components/inline-edit/design-guidelines
+  - Notion database title cell: https://www.notion.com/help/intro-to-databases
+  - MUI X DataGrid editing(isCellEditable): https://mui.com/x/react-data-grid/editing/
+  - AG Grid cell editing(editable): https://www.ag-grid.com/react-data-grid/cell-editing/
+---
+
+# InlineEdit 設計原則
+
+**Layout Family**:composite。**edit 態委派 Family 4（Field Control Layout）**——直接渲染 Field 控件（預設 `<Input>`），其 layout / focus contract 由 Field 擁有，不新增 primitive。**view 態同樣委派 Family 4（Model A）**——值-格式化路徑委派 `<Control mode="view">`、純值/標題路徑委派 `fieldViewGeometry`（見「幾何典範」）；InlineEdit 本體只擁有可編輯提示、啟動與 focus 生命週期。
+
+## 定位
+
+**實作基礎:自建 + composes Field 家族**（`renderEdit` 預設 `<Input>`）。
+
+為何自建而非 Field prop/variant:InlineEdit 的本質是**兩個顯示態之間的 toggle 狀態機**(純值 view ↔ 完整 Field 控件 edit)+ **就地編輯的進入/退出/commit/cancel 生命週期**。這是 Field 控件之上的**互動編排層**,不是某個 Field 控件的視覺 variant——Field 控件本身永遠是「一直可編輯的輸入框」,InlineEdit 才決定「何時顯示成純文字、何時顯示成輸入框」。故它 **compose** Field(消費 `<Input>` 當 edit 態),而非擴充 Field。
+
+一句話:**Field 控件回答「這個值長什麼樣、怎麼編輯」;InlineEdit 回答「這個值平常是純文字,想改時才變成 Field 控件」**。
+
+## Controlled-only rationale（Dim 26）
+
+本元件採 **controlled-only**:`value` + `onCommit`,不支援 `defaultValue` uncontrolled fallback。對齊 Field 家族 7 個 controlled-only 元件慣例(Combobox / DatePicker / TimePicker / SelectMenu / LinkInput / NumberInput / PeoplePicker,rationale 見各 spec 同名段)。就地編輯的語意本質 = **值住在 consumer**(detail-pane 資料層),`onCommit` 單向回寫;內部已有 draft 草稿層(進 edit 以 `value` 為初值、結算才 commit),再開 uncontrolled 會產生 draft ↔ internal value 雙層 sync race。未來要改 dual-mode 需 `useControllableState` helper,屬 major API 擴充,目前不在 scope。
+
+## 互動模型（view ↔ edit 二態 canonical;hover 是 view 子態）
+
+| 態 | 視覺 | 行為 |
+|----|------|------|
+| **view**（靜止） | 純值 / 格式化 renderRead,寬度 fill 容器,**透明邊框（預留、不可見）、無底色**(視覺 = 純內容) | editable 時隱形 Pressable 提供 click / 鍵盤 Tab focus / Enter·Space 進 edit |
+| **view + hover**（editable 限定） | **灰色底色 `bg-neutral-hover` + `rounded-md`**(**非邊框**)+ cursor | 提示「這裡可點擊編輯」 |
+| **view + focus-visible**（editable 限定,鍵盤） | 外框染 **`border-primary` 藍框**(消費 Field edit focus 語言,**非 Button ring**) | Enter / Space → 進 edit |
+| **edit** | **真正的 Field 控件**(`mode="edit"` 完整 chrome:border + focus 藍框 + input) | 回歸 field-controls edit canonical;blur/Enter → commit、Esc → cancel |
+
+只有 **view ↔ edit 二態**(hover / focus-visible 是 view 的子態,非第三態);與 DataTable cell 是同一份「就地編輯 host」語義(`../Field/field-controls.spec.md`「軸二 就地編輯 host」段)。
+
+**退出 edit 態(focus 分流)**:
+- **滑鼠 blur**(點外面)→ `commit`(草稿有變更才觸發 `onCommit`),**焦點刻意不送回**——回到純 view,不搶焦
+- **Enter**(鍵盤)→ `commit`,**焦點送回 view 按鈕** + focus-visible 顯藍框(鍵盤焦點不遺失)
+- **Esc**(鍵盤)→ `cancel`(放棄草稿還原 view 態,不 commit),焦點同送回 view 按鈕
+- 分流理由:鍵盤路徑需焦點連續(a11y);滑鼠 blur = 使用者意圖已在別處,強拉焦點回來是搶焦。`focus-visible` 保證只有鍵盤路徑顯藍框。
+- **exit 由 InlineEdit 保證、不靠 consumer 自接(2026-07-17 root cause 修:blur 後 chrome 殘留)**:自訂 `renderEdit`(Select/DatePicker 等 overlay 控件)若只接 `onChange→commit`、不接 dismiss,**不選直接點外面**時舊設計卡 `editing=true`(edit chrome 殘留)。修:InlineEdit 用 **document-level pointerdown-outside**(對齊 [Radix DismissableLayer](https://www.radix-ui.com/primitives/docs/utilities/dismissable-layer) + [Atlassian inline-edit](https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/inline-edit.tsx) click-outside)—— editing 時點在 edit 子樹外且不在本 edit popover 內 → `commit` 回 view;+ `onBlur` focusout 補 tab-out 路徑。**任何控件(含 overlay)blur/點外面都保證回 display**,pixel 驗證 `probe-inline-edit-align.mjs`(點 Status 進 edit→blur→`editing=0`)。
+
+## editable 閘（無 disabled 態）
+
+`editable?: boolean`(預設 true)。`editable=false` → view 態**無 hover 入口、不渲染隱形 Pressable、無藍框、不可進 edit,且不灰化**——就地編輯 host **無 disabled 態**,鎖定 = 純 view 無入口(detail-pane 權限鎖定語意)。與 DataTable cell 的 `editable:(row)=>boolean` 判準閘是**同一份語義**(`../Field/field-controls.spec.md`「軸二」);世界級就地編輯 grid 同模型:MUI X isCellEditable(https://mui.com/x/react-data-grid/editing/)/ AG Grid editable(https://www.ag-grid.com/react-data-grid/cell-editing/)。永久唯讀資料 → 用 `<Control mode="view">`;隨權限切換可編/不可編 → `editable`;**不用 disabled**(灰化是表單 disabled 語言,不是就地編輯語言)。
+
+## 幾何典範（Model A 委派模型,2026-07-16 round16 user GO;推翻 2026-07-09「自帶外框幾何」版）
+
+InlineEdit **不自帶 geometry cva**(M17 消重)——view 態幾何兩路來源,皆消費既有 SSOT:
+
+| 路徑 | 幾何來源 | 說明 |
+|------|---------|------|
+| **值-格式化**(Select→Tag / 日期 / avatar) | 委派 `<Control mode="view">`(view×default = edit 幾何減 chrome) | 幾何 + 內部間距(多 tag gap / avatar↔label)皆由控件 view mode 提供——view 與 edit **同一顆控件、只差 chrome** → 天生一致、零偏移 |
+| **純值 / 標題**(`String(value)` / `as="h1"`) | `fieldViewGeometry(size, multiline)` helper(`../Field/field-wrapper.tsx`,view×default 幾何 SSOT) | = `px-[var(--field-px)]` + `min-h-[var(--field-height-{size})]`;單行 `items-center`、多行 `items-start py-2` |
+
+InlineEdit 本體只給:**對齊盒(-mx orientation-aware)+ 委派 view 統一 field-px + exit 保證 + hover bg + focus 藍框 + 隱形 Pressable**。
+
+**對齊盒(-mx orientation-aware,2026-07-17 移除 fieldCtx gate — root cause 修)**:
+- **對齊 root invariant**:固定 `-mx-[--field-px]` 要能把值/tag/avatar 左緣拉到 label x=0,**充要條件 = 委派控件 view 左 px 恆 = field-px**。故 InlineEdit **兩條 view 路徑都用同一個 `fieldViewGeometry`(field-px + min-h + py)**:純值/標題路徑直接套;**委派控件路徑(renderRead)也用 `fieldViewGeometry` 包住**(委派控件 bare view 皆 0px 左內距 → 包住後統一 field-px)。這樣 tag/avatar/date 全對齊 label(不碰任何控件的 tagPadding)。
+- **vertical(預設,含 standalone)** → `-mx-[var(--field-px)]` + `w-[calc(100%+2*var(--field-px))]`:整塊拉到欄左緣 → 值/tag 左緣落 label x=0(= [Atlassian read-view](https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx) 固定負邊距對照)。**-mx 只依 orientation、不依 fieldCtx**(spec Model A 原意;舊 `fieldCtx &&` gate 讓 standalone 不對齊 = bug,已移除)。-mx bleed field-px 到容器 padding = 刻意(hover/edit 才顯真實邊界)→ consumer 放 ≥field-px padding 容器
+- **horizontal** → `w-full min-w-0`,**不用 -mx**:值內縮 px = 對齊 sibling 控件
+- **edit 態完全繼承原 field**(Jira 式,user 2026-07-17 拍板):edit **不套** field-px 統一,tag 保留 tagPadding 等原生樣式。純文字 view↔edit 零跳;tag 進 edit 有 ~6px 微移(= Jira 式,可接受)。pixel 驗證 `scripts/probe-inline-edit-align.mjs`(VerticalFieldForm plain/tag/多行 Δ≤1px)
+
+**多行(multiline)**:view = `items-start py-2`,**= Textarea edit `py-2`**(textarea.tsx base)——`scripts/inline-edit-view-geometry-invariant.mjs` 機械鎖此契約(Textarea py 一改即紅)。
+
+**「底色範圍 = 輸入框範圍」不變量**:view 與 edit 兩態共用同一對齊盒(同寬、同 1px 邊框盒),幾何同源(view×default = edit 幾何減 chrome),故 hover 底色與 edit 輸入框逐 pixel 對齊、態切換零位移。(舊版 read 外框 `w-full`+`-mx` 疊加 → 右側短一截、整塊左偏,已修;2026-07-16 -mx 由恆定改條件化;2026-07-17 進一步移除 fieldCtx gate → 純 orientation-aware,委派 view 統一 fieldViewGeometry field-px,standalone 也對齊。)
+
+**尺寸預設 = `sm`**（2026-07-09 user 拍板）:view 態無邊框、視覺即純文字,尺寸過大會使版面鬆散;consumer 可傳 `size` 覆寫,標題場景另用 `readClassName` 疊大字級。
+
+**在 `<Field>` 內也是 `sm`**(2026-07-28 user 拍板):Field 的預設 `md` 是「沒人決定過」的預設值,不得壓過本元件宣告的 `sm`。實作雙通道 —— 靜態 `InlineEdit.fieldPreferredSize = 'sm'` 供 Field 直接子元件同步偵測,加上掛載時的 `useRegisterFieldPreferredSize('sm')` 補位(包 wrapper / `React.memo` / HOC 會遮蔽靜態);控件自身尺寸則由 `useResolvedFieldSize` 依 `sizeExplicit` 同步解析,不等註冊。**唯有 consumer 顯式 `size`(在 Field 或 InlineEdit 上)才覆寫**。機制與失效語意 owner → `Field/field.spec.md`「Control 偏好尺寸 SSOT」。
+
+**單行 view 恆一行**(2026-07-28 user 拍板):`multiline=false` 的 view 態溢出**不換行**,一律 ellipsis,且**截斷才顯 tooltip**顯示完整值(規則 owner:`Tooltip/tooltip.spec.md`「截斷文字 → tooltip」+ `truncated-text.spec.md`)。**實作 = `useTruncated` 自組而非 `<TruncatedText>`**:view 上疊著透明 Pressable(click-to-edit 入口)會吞掉內層所有 hover,tooltip trigger 必須掛在**整個 view 容器**、量測留在內層值 span —— 這正是 truncated-text.spec 對「trigger 需自控」場景指定的 escape(2026-07-28 user 實測抓到 primitive 直用時 tooltip 永不開)。委派 view(`renderRead`)同一條規則、同一個外層 Tooltip:委派控件自帶的截斷 tooltip(Input `<TruncatedText>` / Tag)trigger 在內層,editable 時同樣被 Pressable 攔截 —— 故外層容器 Tooltip 一併服務委派路徑:`useTruncated` 傳自訂 `measure`(`hooks/use-truncated.ts` options.measure 即為此類自訂策略開的口)走訪 wrapper 子樹,任一 `.truncate` 後代溢出即視為截斷;tooltip 內容 = wrapper 當下 DOM 的 `textContent`(完整格式化文字;非 string `T` 不可 `String(value)`)。`editable=false` 不渲染 Pressable → 委派控件自身 tooltip 可達,外層讓位不重複顯示。多行(`multiline`)維持 `pre-wrap` 忠實呈現。
+
+**多行 edit 高度隨內容**(2026-07-28 user 拍板):view 態高度由內容決定,edit 態必須同源,否則 read↔edit 跳高。預設 `Textarea autoSize`(`field-sizing: content`),consumer 以 `editMaxRows` 設上限、超過改捲動。與 DataTable cell 共用同一份 `autoSize` 實作(原本只有 cell 有呼叫端膠水 → 兩者漂移)。
+
+**核心不變量:view 態 hover = 背景 tint;view 態 focus = Field 藍框（`border-primary`）,與 edit 態同源。** hover（滑鼠懸停）用底色、focus（鍵盤選中）用藍框——藍框是 edit focus 的預覽,view→edit 一路都是藍框、不會 ring→框跳一下;靜止（無 hover/focus）則透明邊框不可見 = 純值。
+
+## 型別化 view + 多行 + 鍵盤 SSOT（2026-07-09 L2）
+
+InlineEdit 為**泛型 `<T>`**（非只 string）:`value: T` / `onCommit: (next: T) => void`。三個 render 面向:
+
+| Prop | 作用 | 預設 | SSOT 鐵律 |
+|---|---|---|---|
+| `renderRead?(value)` | view 態格式化顯示 | `String(value)`（空 → placeholder） | 要顯 **Tag / 日期 / option label**,**渲染對應控件的 `mode="view"`**（如 `<Select mode="view" display="tag">`），**禁自刻**——格式化 SSOT 住在該控件的 view mode |
+| `renderEdit?(props)` | edit 態控件 | `multiline`→`<Textarea>` / 否則 `<Input>` | 非 string 值必傳（預設路徑僅 string） |
+| `multiline?` | 多行（Jira description 類） | false | view `items-start py-2` 換行（= Textarea edit py-2,見「幾何典範」）、edit Textarea（Enter=換行、Cmd/Ctrl+Enter 或 blur 提交） |
+
+**Tag 顯示的 SSOT 對齊（user 2026-07-09 問）**:「select 值 → Tag」的格式化住在 **Select 的 `mode="view" display="tag"`**（`select.tsx` ReadonlyDisplay Tag 分支）—— 這正是 **DataTable 格子消費的同一份**（`cell-registry.tsx` SelectCell view 分支）。InlineEdit view 態顯 Tag = `renderRead={(v) => <Select mode="view" display="tag" value={v} options={opts} />}`,**view 與 edit 用同一個 Select、只切 mode → 格式零分歧**。此即「乾淨對齊」:InlineEdit 從不重刻 Tag,格式化永遠委派給控件的 view mode。示範見 `inline-edit.stories.tsx` `SelectTagField`。
+
+**鍵盤結算 SSOT**:Enter=commit / Esc=cancel + **中文 IME 組字 guard** 抽為 `../Field/field-edit-keys.ts` `makeEditSettleKeyHandler`,**InlineEdit 與 DataTable cell（`cell-registry.tsx`）同源消費**（2026-07-09 抽出;原本 InlineEdit 漏 IME guard = 中文選字 Enter 誤提交半截組字 bug,現已修）。edit-in-place SSOT 研究（2026-07-09,6-agent + 世界級）結論:兩 host 的 draft 擁有權 / state locus（單實例 vs 表格級 keyed）/ focus model 根本不同,故**不抽大共用狀態機**（違 M21 + 破壞表格虛擬捲動效能）,只抽此純鍵盤結算片段。世界級共識 = **field 控件 + 型別 registry 可共用,edit-in-place orchestration 各自實作**（見 `../Field/field-controls.spec.md`「Field 框架地圖」段 cite）。
+
+## 世界級對照
+
+| DS | view 態 | hover affordance | 進 edit | 鍵盤 |
+|----|---------|-----------------|---------|------|
+| **Atlassian inline-edit**（[read-view.tsx](https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx)） | 純值 + 隱形 Pressable | **背景 tint**（`background.neutral.subtle.hovered`,**非邊框**） | click read view | 隱形 button focus + Enter;5px drag threshold 防選字誤觸 |
+| **PatternFly inline-edit** | value 文字 | 可編輯提示 | value/input 二態 toggle | Enter commit / Esc cancel |
+| **Notion title cell** | 純文字 | hover 浮 affordance | click 編輯 | — |
+
+三家共識:view 態 = 純值、hover = 輕背景提示（非重邊框）、click 或鍵盤進 edit、edit = 真正的輸入控件。本 DS 對齊此模型;`bg-neutral-hover` = 本 DS 的「neutral subtle hover」等價 token。
+
+**view 態 focus canonical**（2026-07-09）:Atlassian read-view 的隱形 Pressable focus 時,外框顯 `color.border.focused` **實線 solid border**（非 ring）——[read-view.tsx](https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx) `&:focus + div { borderColor: token('color.border.focused') }`。本 DS 對齊此語言:view focus = `border-primary`(= Field edit focus 藍框),使 view→edit focus 視覺連續,不引入第三種（ring）focus 語言。
+
+**view 態 typography canonical**（2026-07-09）:Atlassian inline-edit / PatternFly 將 view 態字級**委派**給 consumer（readView 不強加字體,由外層 context 決定）。本 DS 更 opinionated——view 態預設消費 `fieldDisplayTextClass(size)`（sm/md→`text-body`,lg→`text-body-lg`,`../Field/field-wrapper.tsx` Field view 字體 SSOT),使 **plain 用法**（`<InlineEdit value onCommit />`）view 字級即 = edit `<Input>`（`text-body`）= `<Input mode="view">` 字級,三者一致零跳字;`readClassName`（如標題 `text-h4 font-bold`）僅作特例 override 疊其後。對齊 [Atlassian inline-edit read-view](https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx) 委派模型,並補上「plain 用法即 canonical」的預設。
+
+**狀態 data 屬性**（可測性）:外層容器 `data-editing`（read/edit 態）、read 元素 `data-empty`（空值）——供 audit / Playwright 斷言態切換與空值渲染（Dice UI data-attribute idiom,對齊 M32 pixel/DOM 可驗）。
+
+## 何時用
+
+- **標題就地編輯**:任務/文件/專案標題,平常是大標題純文字,點一下改（`as="h1"` + `readClassName` 帶標題字級）。
+- **detail pane metadata 就地編輯**:單一值欄位（負責人備註、外部連結、簡短描述）平常純文字呈現,點擊即編。
+- 語意 = **「這個值大部分時間是被閱讀的,偶爾才編輯」**——閱讀優先、編輯次要。
+
+## 何時不用
+
+- **表單欄位** → 直接用 `<Field>` + Field 控件(表單本來就是編輯情境,不需要 view 態偽裝成純文字)。
+- **DataTable 密集可編輯格** → 用 naked cell(host cell 自管 border + focus、hover outline affordance;見 `field-controls.spec.md`「Cell(naked variant)」),不是每格包一個 InlineEdit 狀態機。
+- **一律唯讀展示**(不可編) → 用 `<Input mode="view">` / 純文字,不需要 Pressable;**隨權限暫時鎖定** → 留 InlineEdit 傳 `editable=false`(不灰化,見「editable 閘」)。
+- **多欄位一次編輯** → 用表單(進入一次編輯全部欄位),不是逐欄 inline edit。
+
+## 近親分界
+
+| 元件 | 分界 |
+|------|------|
+| **Field 控件**（Input/Select/Textarea…） | 一直可編輯的輸入框;InlineEdit 讓它「平常是純文字,想改才現身」 |
+| **`<Input mode="view">`** | 純展示(無互動、不可編);InlineEdit 的 view 態可點擊進 edit |
+| **naked cell**（DataTable） | 表格密集網格的 cell-as-input,host cell 自管 chrome;InlineEdit 是單一 standalone 欄位的閱讀↔編輯 toggle |
+
+## 常見誤解
+
+- **「view 態 hover 該加邊框」** → 錯。hover = 背景 tint（`bg-neutral-hover`）;邊框是 edit 態語言。
+- **「edit 態要自己刻 input chrome」** → 錯。edit 態 = 真正的 Field 控件(預設 `<Input>`),完全回歸 field-controls edit canonical,不重刻。
+- **「大標題 inline edit 要自己做 focus/commit/esc」** → 錯。用 InlineEdit,生命週期(commit/cancel/Esc/focus 返回)由 primitive 統一處理。
+
+## 空值
+
+`value` 為空字串 / null 時,view 態顯示 `placeholder`(若有)+ `text-fg-muted`;無 placeholder 則空白。edit 態進入時草稿初值 = 空字串,顯示空 input。（不用唯讀展示語言的半形 `-` dash——InlineEdit 是可編輯欄位,空值 = 「還沒填、點來填」,dash 是唯讀展示語言。）
+
+## 驗證
+
+InlineEdit 本身不含驗證邏輯;若 edit 態需要驗證,consumer 透過 `renderEdit` 傳入帶 `error` 的 Field 控件,並在 `onCommit` 做值檢查（reject 時可不呼叫真正的資料更新）。此分層對齊 field-controls「error 正交於 mode」原則。
+
+## Loading
+
+InlineEdit 不含 async loading state。若 commit 需要 async 儲存,consumer 在 `onCommit` 內自行處理 optimistic update / toast;edit 態的 debounce/loading 由 `renderEdit` 傳入的控件(如 `<Input loading>`)承擔。
+
+## A11y 預設
+
+**ARIA**:
+- view 態隱形 Pressable = `<button type="button">`,帶 `aria-label`(預設「編輯 {label}」)——螢幕閱讀器朗讀「可編輯」意圖。**僅 editable 時渲染**;`editable=false` 無 Pressable = 純 view(非 disabled,不進 tab order 也不灰化)。
+- view 態語意標籤（`as`,預設 `span`;標題傳 `h1`/`h2`）獨立於 button 之外——`as="h1"` 保留文件大綱結構（HTML 內容模型不允許 heading 巢狀於 button,故隱形 Pressable 與語意標籤分離,對齊 [read-view.tsx](https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx) hidden-Pressable pattern）。
+- edit 態控件帶 `aria-label`（= `label`）。
+
+**Keyboard**:
+| 鍵 | view 態 | edit 態 |
+|----|---------|---------|
+| `Tab` | focus view 按鈕(僅 editable;外框染 `border-primary` 藍框,**非** ring;對齊本 spec 其餘段) | 依控件內部 focus 行為 |
+| `Enter` / `Space` | 進 edit | `Enter` commit(焦點回 view 按鈕) |
+| `Esc` | — | cancel(還原不 commit,焦點回 view 按鈕) |
+
+**Focus 管理(分流)**:進 edit 態自動 focus 控件（`autoFocus`);**鍵盤結算**(Enter commit / Esc cancel)後焦點送回 view 按鈕 + focus-visible 藍框(焦點不遺失);**滑鼠 blur 結算刻意不回焦**——回純 view 不搶焦(理由見「退出 edit 態(focus 分流)」段)。
+
+## shadcn passthrough 例外說明
+InlineEdit 是 **composite 編排層**(view 對齊盒 + 隱形 Pressable + 動態生成的 edit 控件),遵循 shadcn 結構 idiom(forwardRef + displayName)但**無 `...props` spread**:外層 div 只是對齊盒、非 consumer 可預期的互動 surface(spread 目標不明——view 按鈕?edit 控件?),DOM 級屬性應透過 `renderEdit` / `renderRead` 下傳給真正的控件;`ref` / `className` 附著於外層對齊盒。`asChild` 不支援(composite 非 Slot-compat,Slot 慣例見 https://www.radix-ui.com/primitives/docs/utilities/slot)。
+
+## 禁止事項
+
+- ❌ view 態 hover 用邊框——用 `bg-neutral-hover` 背景 tint（邊框是 edit 態語言）
+- ❌ edit 態手刻 input chrome——用 Field 控件（預設 `<Input>`)
+- ❌ 用 InlineEdit 包 DataTable 密集可編輯格——用 naked cell
+- ❌ 空值顯示唯讀展示的半形 `-` dash——InlineEdit 是可編輯欄位,空值 = placeholder 或空白
+- ❌ view 態語意標籤用 heading 時把它塞進 button——用隱形 Pressable 疊加,保留文件大綱
+- ❌ 用 disabled / 灰化表達鎖定——就地編輯無 disabled 態,鎖定 = `editable=false` 純 view 無入口、不灰化(見「editable 閘」)
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `field.spec.md`

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

@@ -0,0 +1,261 @@
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { InlineEdit } from './inline-edit'
+import { Select } from '@/design-system/components/Select/select'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+
+const meta: Meta<typeof InlineEdit> = {
+  title: 'Design System/Components/InlineEdit/展示',
+  component: InlineEdit,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { description: { component: '讓既有文字或選擇值在原位置切換為編輯控制項，保留檢視與編輯的版面連續性。適用低風險、可快速儲存的單欄位修改，不取代完整表單。' } },
+  },
+}
+export default meta
+type Story = StoryObj<typeof InlineEdit>
+
+// 受控 helper —— InlineEdit 的 value 由 consumer 持有,onCommit 回寫
+type StatefulProps = Omit<React.ComponentProps<typeof InlineEdit>, 'onCommit'>
+function StatefulInlineEdit({ value: initial, ...props }: StatefulProps) {
+  const [value, setValue] = React.useState(initial)
+  return <InlineEdit {...props} value={value} onCommit={setValue} />
+}
+
+/* ── 真實業務:工作項目詳情面板標題就地編輯 ── */
+export const TaskTitle: Story = {
+  name: '任務標題就地編輯',
+  render: () => {
+    const [title, setTitle] = React.useState('Fix flaky checkout e2e test on Safari')
+    return (
+      <div className="w-[560px] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]">
+        <p className="mb-1 text-caption text-fg-secondary">PROJ-482</p>
+        <InlineEdit
+          as="h1"
+          value={title}
+          onCommit={setTitle}
+          label="task title"
+          readClassName="text-h4 font-bold text-foreground"
+          placeholder="Add a title…"
+        />
+        <p className="mt-4 text-body text-fg-muted">
+          標題平常是純文字,滑鼠移入顯示灰底提示可編輯;點擊(或鍵盤 Tab + Enter)切成輸入框,Enter 儲存、Esc 取消。
+        </p>
+      </div>
+    )
+  },
+}
+
+/* ── 真實業務:詳情面板多個 metadata 欄位逐欄就地編輯 ── */
+function MetaRow({ label, value, placeholder }: { label: string; value: string; placeholder?: string }) {
+  return (
+    <Field orientation="horizontal" labelWidth="128px">
+      <FieldLabel>{label}</FieldLabel>
+      <StatefulInlineEdit value={value} label={label} placeholder={placeholder} size="sm" />
+    </Field>
+  )
+}
+
+export const MetadataFields: Story = {
+  name: '詳情欄位就地編輯',
+  render: () => (
+    <div className="w-[440px] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]">
+      {/* heading → fields = tight（functional labeling）;fields 彼此 = loose（parallel 獨立欄位,layoutSpace.spec.md 親疏 3 級） */}
+      <h2 className="mb-[var(--layout-space-tight)] text-body font-bold text-foreground">Details</h2>
+      <div className="flex flex-col gap-[var(--layout-space-loose)]">
+        <MetaRow label="Summary" value="Q3 launch checklist owner handoff" />
+        <MetaRow label="Story points" value="5" />
+        <MetaRow label="External link" value="figma.com/file/checkout-flow" placeholder="Add a link…" />
+        <MetaRow label="Reviewer note" value="" placeholder="Add a note…" />
+      </div>
+    </div>
+  ),
+}
+
+/* ── 狀態 matrix:view / hover / edit（二態 canonical,hover 是 view 子態;play 驅動 hover + edit 態顯示）── */
+function StateRow({
+  caption,
+  children,
+  ...rest
+}: { caption: string; children: React.ReactNode } & React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div {...rest}>
+      {/* standalone(無 Field)的 InlineEdit 不帶 -mx(w-full),view 值自帶 px-field-px 內距
+          (fieldViewGeometry);caption 同步 px-field-px 讓說明與值文字左緣對齊 */}
+      <p className="mb-2 px-[var(--field-px)] text-caption text-fg-muted">{caption}</p>
+      {children}
+    </div>
+  )
+}
+
+export const States: Story = {
+  name: '狀態:檢視/懸停/編輯',
+  render: () => (
+    <div className="flex w-[440px] flex-col gap-6">
+      <StateRow caption="view(靜止)—— 純值,透明邊框(預留、不可見)、無底色">
+        <StatefulInlineEdit value="Design review notes" label="標題" />
+      </StateRow>
+      <StateRow
+        caption="view + hover —— 灰底 bg-neutral-hover + rounded-md(非邊框)"
+        data-testid="inline-edit-hover-row"
+      >
+        <StatefulInlineEdit value="Design review notes" label="標題" />
+      </StateRow>
+      <StateRow
+        caption="edit —— 真正的 Field 控件(border + focus 藍框 + input)"
+        data-testid="inline-edit-edit-row"
+      >
+        <StatefulInlineEdit value="Design review notes" label="標題" />
+      </StateRow>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const { userEvent } = await import('@storybook/test')
+    // 只標記第二列；真實 CSS :hover 由 visual-audit 的 Playwright pointer 建立。
+    const hoverBtn = canvasElement
+      .querySelector('[data-testid="inline-edit-hover-row"]')
+      ?.querySelector('button')
+    if (hoverBtn) hoverBtn.setAttribute('data-visual-hover-target', '')
+    // edit 態:點擊第三列 → 切成真正的 Input 控件
+    const editBtn = canvasElement
+      .querySelector('[data-testid="inline-edit-edit-row"]')
+      ?.querySelector('button')
+    if (editBtn) await userEvent.click(editBtn)
+  },
+}
+
+/* ── 真實業務:工作項目 Status 就地編輯(型別化 view = Tag)──
+   SSOT 示範:view 態的 Tag **不是** InlineEdit 自刻,而是渲染 `<Select mode="view" display="tag">`
+   —— 「select 值 → Tag」的格式化 SSOT 住在 Select 的 view mode(= DataTable 格子消費的同一份)。
+   view 與 edit 用同一個 Select、只切 mode,格式零分歧。 */
+const STATUS_OPTIONS = [
+  { value: 'todo', label: 'To Do', tagVariant: 'neutral' },
+  { value: 'in-progress', label: 'In Progress', tagVariant: 'blue' },
+  { value: 'in-review', label: 'In Review', tagVariant: 'yellow' },
+  { value: 'done', label: 'Done', tagVariant: 'green' },
+]
+
+// 架構理由(移出 story name,per story-rules.md name 必人話):view 態顯示為 Tag,SSOT = Select
+// 的 view mode —— InlineEdit 委派 Select 控件,view 態消費 Select 的 view 呈現(標籤/色點)。
+export const SelectTagField: Story = {
+  name: '狀態就地編輯(讀取時顯示為標籤)',
+  render: () => {
+    const [status, setStatus] = React.useState('in-progress')
+    return (
+      <Field
+        orientation="horizontal"
+        labelWidth="128px"
+        className="w-[440px] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]"
+      >
+        <FieldLabel>Status</FieldLabel>
+        <InlineEdit<string>
+          value={status}
+          onCommit={setStatus}
+          label="status"
+          size="sm"
+          // view:Select 的 view mode 輸出 Tag(格式化 SSOT 住在 Select,InlineEdit 不自刻)。
+          // Tag **盒子左緣**對齊同欄其他純文字值(horizontal Field:值落內容欄左緣 + field-px,
+          // 不用 -mx),tag 文字被 pill 內距自然縮排 —— 對齊 Meegle 實測
+          // (PIL 量測 2026-07-10:Meegle pill box=值左緣、text 縮排 ~8px@1x)。**不做 text outdent**。
+          renderRead={(v) => (
+            <Select mode="view" display="tag" size="sm" value={v} options={STATUS_OPTIONS} />
+          )}
+          // edit:同一個 Select 切 edit mode + 立即開選單;選完即 commit 回 view
+          renderEdit={(p) => (
+            <Select
+              autoFocus
+              display="tag"
+              size="sm"
+              value={p.value}
+              options={STATUS_OPTIONS}
+              defaultOpen
+              onChange={(next) => {
+                p.onChange(next as string)
+                p.commit()
+              }}
+            />
+          )}
+        />
+      </Field>
+    )
+  },
+}
+
+/* ── 真實業務:工作項目 Description 多行就地編輯(Jira description 類)──
+   multiline:view 態換行顯示、edit 態預設 Textarea(Enter=換行、Cmd/Ctrl+Enter 或 blur 提交)。 */
+export const MultilineDescription: Story = {
+  name: '多行描述就地編輯(Jira 描述欄類)',
+  render: () => {
+    const [desc, setDesc] = React.useState(
+      'Safari 上點擊結帳時,e2e 測試會間歇性失敗。\n\n重現:連跑測試 5 次,約 2 次失敗;疑似 checkout webhook race。',
+    )
+    return (
+      <div className="w-[560px] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]">
+        <Field orientation="vertical">
+          <FieldLabel>DESCRIPTION</FieldLabel>
+          <InlineEdit
+            multiline
+            value={desc}
+            onCommit={setDesc}
+            label="description"
+            placeholder="Add a description…"
+          />
+        </Field>
+      </div>
+    )
+  },
+}
+
+/* ── 真實業務:工作項目詳情面板 —— vertical Field(FieldLabel + control)+ InlineEdit ──
+   混合 plain / Tag / 多行欄位,驗證 Tag 值與 FieldLabel + 其他 plain 值的左緣視覺對齊。 */
+export const VerticalFieldForm: Story = {
+  name: '詳情面板:垂直欄位就地編輯',
+  render: () => {
+    // InlineEdit 是 <Field> 的直接子時，Field 同步讀取靜態 fieldPreferredSize='sm'；若經過
+    // wrapper / memo / HOC，InlineEdit 仍會在掛載時註冊偏好，讓 Field 控件槽跟上 sm。
+    // Field 或 InlineEdit 顯式 size 永遠優先(對照 anatomy CascadeDemo)。
+    const [assignee, setAssignee] = React.useState('Alex Rivera')
+    const [status, setStatus] = React.useState('in-progress')
+    const [desc, setDesc] = React.useState('Safari 上點擊結帳時,e2e 測試會間歇性失敗。')
+    return (
+      <div
+        data-testid="vfield-form"
+        className="flex w-[420px] flex-col gap-[var(--layout-space-loose)] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]"
+      >
+        <Field orientation="vertical">
+          <FieldLabel>Assignee</FieldLabel>
+          <InlineEdit value={assignee} onCommit={setAssignee} label="assignee" />
+        </Field>
+        <Field orientation="vertical">
+          <FieldLabel>Status</FieldLabel>
+          <InlineEdit<string>
+            value={status}
+            onCommit={setStatus}
+            label="status"
+            renderRead={(v) => (
+              <Select mode="view" display="tag" size="sm" value={v} options={STATUS_OPTIONS} />
+            )}
+            renderEdit={(p) => (
+              <Select
+                autoFocus
+                display="tag"
+                size="sm"
+                value={p.value}
+                options={STATUS_OPTIONS}
+                defaultOpen
+                onChange={(next) => {
+                  p.onChange(next as string)
+                  p.commit()
+                }}
+              />
+            )}
+          />
+        </Field>
+        <Field orientation="vertical">
+          <FieldLabel>Description</FieldLabel>
+          <InlineEdit multiline value={desc} onCommit={setDesc} label="description" />
+        </Field>
+      </div>
+    )
+  },
+}