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

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

@@ -9,79 +9,100 @@ 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>`），幾何/邊框/focus 全繼承 `fieldWrapperStyles`，不新增 layout primitive。**read 態為 self-contained 純文字承載 + 隱形 Pressable**（絕對定位透明 `<button>`），只負責「看起來像純文字、hover 才有 affordance、點擊進 edit」。
+**Layout Family**:composite。**edit 態委派 Family 4（Field Control Layout）**——直接渲染 Field 控件（預設 `<Input>`），幾何/邊框/focus 全繼承 `fieldWrapperStyles`，不新增 layout primitive。**view 態幾何同樣委派 Family 4（Model A,不自帶 geometry cva）**——值-格式化路徑委派 `<Control mode="view">`、純值/標題路徑套 `fieldViewGeometry` helper（見「幾何典範」）;本體只疊 hover bg + focus 藍框 + 隱形 Pressable（絕對定位透明 `<button>`），負責「看起來像純內容、hover 才有 affordance、點擊進 edit」。
 
 ## 定位
 
 **實作基礎:自建 + composes Field 家族**（`renderEdit` 預設 `<Input>`）。
 
-為何自建而非 Field prop/variant:InlineEdit 的本質是**兩個顯示態之間的 toggle 狀態機**(純文字 read view ↔ 完整 Field 控件 edit view)+ **就地編輯的進入/退出/commit/cancel 生命週期**。這是 Field 控件之上的**互動編排層**,不是某個 Field 控件的視覺 variant——Field 控件本身永遠是「一直可編輯的輸入框」,InlineEdit 才決定「何時顯示成純文字、何時顯示成輸入框」。故它 **compose** Field(消費 `<Input>` 當 edit 態),而非擴充 Field。
+為何自建而非 Field prop/variant:InlineEdit 的本質是**兩個顯示態之間的 toggle 狀態機**(純值 view ↔ 完整 Field 控件 edit)+ **就地編輯的進入/退出/commit/cancel 生命週期**。這是 Field 控件之上的**互動編排層**,不是某個 Field 控件的視覺 variant——Field 控件本身永遠是「一直可編輯的輸入框」,InlineEdit 才決定「何時顯示成純文字、何時顯示成輸入框」。故它 **compose** Field(消費 `<Input>` 當 edit 態),而非擴充 Field。
 
 一句話:**Field 控件回答「這個值長什麼樣、怎麼編輯」;InlineEdit 回答「這個值平常是純文字,想改時才變成 Field 控件」**。
 
-## 互動模型（read / hover / edit 三態 canonical）
+## 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 子態）
 
 | 態 | 視覺 | 行為 |
 |----|------|------|
-| **read**（靜態） | 純文字,寬度 fill 容器,**透明邊框（預留、不可見）、無底色**(視覺 = 純文字) | 隱形 Pressable 提供 click / 鍵盤 Tab focus / Enter·Space 進 edit |
-| **read + hover** | **灰色底色 `bg-neutral-hover` + `rounded-md`**(**非邊框**)+ cursor | 提示「這裡可點擊編輯」 |
-| **read + focus-visible**（鍵盤） | 外框染 **`border-primary` 藍框**(消費 Field edit focus 語言,**非 Button ring**) | Enter / Space → 進 edit |
-| **edit** | **真正的 Field 控件**(完整 chrome:border + focus 藍框 + input) | 回歸 field-controls edit canonical;blur/Enter → commit、Esc → cancel |
+| **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 態）
 
-**退出 edit 態**:
-- **blur**（點外面）→ `commit`（草稿有變更才觸發 `onCommit`）
-- **Enter** → `commit`
-- **Esc** → `cancel`（放棄草稿,還原 read 態,不 commit）
-- 任一路徑結算後,focus 送回 read 按鈕(鍵盤焦點不遺失)
+`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 語言,不是就地編輯語言)。
 
-## 幾何典範（2026-07-09 user 拍板,每值消費既有 SSOT,零自創）
+## 幾何典範（Model A 委派模型,2026-07-16 round16 user GO;推翻 2026-07-09「自帶外框幾何」版）
 
-| 面向 | 定義 | 消費的 SSOT |
-|------|------|------------|
-| 外框（read/edit 共用） | `-mx-[var(--field-px)]` + `w-[calc(100% + 2*var(--field-px))]` → 左右各對稱外擴 `--field-px`、填滿容器 | `--field-px` |
-| 水平內距 | 文字 `px-[var(--field-px)]`（read=edit 同值）→ 文字左緣與相鄰內容切齊、底色/框外擴 gutter | `--field-px` |
-| 垂直 | `min-h-[var(--field-height-{size})]` + 垂直置中（**無 py token**——Field 家族本就以「固定高度 + 置中」定義呼吸,非 padding；故 InlineEdit 同法,隨 size/density 自動縮放不漂移） | `--field-height-{sm/md/lg}` |
-| hover（read） | `bg-neutral-hover` + `rounded-md`（底色 tint,**非邊框**） | color token + field radius |
-| focus（read/鍵盤） | 透明 `border` 預留、focus 染 `border-primary`（Field focus 藍框語言,**非 ring**） | Field focus canonical |
-| edit | 真正 `<Input>`（border + focus + input），width=fill 填滿外框 | field-controls edit canonical |
+InlineEdit **不自帶 geometry cva**(M17 消重)——view 態幾何兩路來源,皆消費既有 SSOT:
 
-**「底色範圍 = 輸入框範圍」不變量**:read 與 edit 兩態共用同一外框幾何（同 `-mx`+calc 寬、同 `min-h`=field-height、同 1px 邊框盒),故 hover 底色與 edit 輸入框逐 pixel 對齊、態切換零位移。（舊版 read 外框 `w-full`+`-mx` 疊加 → 右側短一截、整塊左偏,已修。）
+| 路徑 | 幾何來源 | 說明 |
+|------|---------|------|
+| **值-格式化**(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` |
 
-**尺寸預設 = `sm`**（2026-07-09 user 拍板）:read 態無邊框、視覺即純文字,尺寸過大會使版面鬆散;consumer 可傳 `size` 覆寫,標題場景另用 `readClassName` 疊大字級。
+InlineEdit 本體只給:**對齊盒(-mx orientation-aware)+ 委派 view 統一 field-px + exit 保證 + hover bg + focus 藍框 + 隱形 Pressable**。
 
-**核心不變量:read 態 hover = 背景 tint;read 態 focus = Field 藍框（`border-primary`）,與 edit 態同源。** hover（滑鼠懸停）用底色、focus（鍵盤選中）用藍框——藍框是 edit focus 的預覽,read→edit 一路都是藍框、不會 ring→框跳一下;靜態（無 hover/focus）則透明邊框不可見 = 純文字。
+**對齊盒(-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)
 
-## 型別化 read view + 多行 + 鍵盤 SSOT（2026-07-09 L2）
+**多行(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` 疊大字級。
+
+**核心不變量: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)` | read 態格式化顯示 | `String(value)`（空 → placeholder） | 要顯 **Tag / 日期 / option label**,**渲染對應控件的 `mode="display"`**（如 `<Select mode="display" display="tag">`），**禁自刻**——格式化 SSOT 住在該控件的 display mode |
+| `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 | read `items-start` 換行、edit Textarea（Enter=換行、Cmd/Ctrl+Enter 或 blur 提交） |
+| `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="display" display="tag"`**（`select.tsx` ReadonlyDisplay Tag 分支）—— 這正是 **DataTable 格子消費的同一份**（`cell-registry.tsx` SelectCell display 分支）。InlineEdit read 態顯 Tag = `renderRead={(v) => <Select mode="display" display="tag" value={v} options={opts} />}`,**read 與 edit 用同一個 Select、只切 mode → 格式零分歧**。此即「乾淨對齊」:InlineEdit 從不重刻 Tag,格式化永遠委派給控件的 display mode。示範見 `inline-edit.stories.tsx` `SelectTagField`。
+**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 | read 態 | hover affordance | 進 edit | 鍵盤 |
+| 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 編輯 | — |
 
-三家共識:read 態 = 純值、hover = 輕背景提示（非重邊框）、click 或鍵盤進 edit、edit = 真正的輸入控件。本 DS 對齊此模型;`bg-neutral-hover` = 本 DS 的「neutral subtle hover」等價 token。
+三家共識:view 態 = 純值、hover = 輕背景提示（非重邊框）、click 或鍵盤進 edit、edit = 真正的輸入控件。本 DS 對齊此模型;`bg-neutral-hover` = 本 DS 的「neutral subtle hover」等價 token。
 
-**read 態 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 對齊此語言:read focus = `border-primary`(= Field edit focus 藍框),使 read→edit focus 視覺連續,不引入第三種（ring）focus 語言。
+**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 語言。
 
-**read 態 typography canonical**（2026-07-09）:Atlassian inline-edit / PatternFly 將讀態字級**委派**給 consumer（read view 不強加字體,由外層 context 決定）。本 DS 更 opinionated——read 態預設消費 `fieldDisplayTextClass(size)`（sm/md→`text-body`,lg→`text-body-lg`,`../Field/field-wrapper.tsx` Field display 字體 SSOT),使 **plain 用法**（`<InlineEdit value onCommit />`）read 字級即 = edit `<Input>`（`text-body`）= `<Input mode="display">` 字級,三態零跳字;`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」的預設。
+**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 可驗）。
 
@@ -93,9 +114,9 @@ InlineEdit 為**泛型 `<T>`**（非只 string）:`value: T` / `onCommit: (next:
 
 ## 何時不用
 
-- **表單欄位** → 直接用 `<Field>` + Field 控件(表單本來就是編輯情境,不需要 read 態偽裝成純文字)。
+- **表單欄位** → 直接用 `<Field>` + Field 控件(表單本來就是編輯情境,不需要 view 態偽裝成純文字)。
 - **DataTable 密集可編輯格** → 用 naked cell(host cell 自管 border + focus、hover outline affordance;見 `field-controls.spec.md`「Cell(naked variant)」),不是每格包一個 InlineEdit 狀態機。
-- **一律唯讀展示**(不可編) → 用 `<Input mode="display">` / 純文字,不需要 Pressable。
+- **一律唯讀展示**(不可編) → 用 `<Input mode="view">` / 純文字,不需要 Pressable;**隨權限暫時鎖定** → 留 InlineEdit 傳 `editable=false`(不灰化,見「editable 閘」)。
 - **多欄位一次編輯** → 用表單(進入一次編輯全部欄位),不是逐欄 inline edit。
 
 ## 近親分界
@@ -103,18 +124,18 @@ InlineEdit 為**泛型 `<T>`**（非只 string）:`value: T` / `onCommit: (next:
 | 元件 | 分界 |
 |------|------|
 | **Field 控件**（Input/Select/Textarea…） | 一直可編輯的輸入框;InlineEdit 讓它「平常是純文字,想改才現身」 |
-| **`<Input mode="display">`** | 純展示(無互動、不可編);InlineEdit 的 read 態可點擊進 edit |
+| **`<Input mode="view">`** | 純展示(無互動、不可編);InlineEdit 的 view 態可點擊進 edit |
 | **naked cell**（DataTable） | 表格密集網格的 cell-as-input,host cell 自管 chrome;InlineEdit 是單一 standalone 欄位的閱讀↔編輯 toggle |
 
 ## 常見誤解
 
-- **「read 態 hover 該加邊框」** → 錯。hover = 背景 tint（`bg-neutral-hover`）;邊框是 edit 態語言。
+- **「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 時,read 態顯示 `placeholder`(若有)+ `text-fg-muted`;無 placeholder 則空白。edit 態進入時草稿初值 = 空字串,顯示空 input。（不用唯讀展示語言的半形 `-` dash——InlineEdit 是可編輯欄位,空值 = 「還沒填、點來填」,dash 是唯讀展示語言。）
+`value` 為空字串 / null 時,view 態顯示 `placeholder`(若有)+ `text-fg-muted`;無 placeholder 則空白。edit 態進入時草稿初值 = 空字串,顯示空 input。（不用唯讀展示語言的半形 `-` dash——InlineEdit 是可編輯欄位,空值 = 「還沒填、點來填」,dash 是唯讀展示語言。）
 
 ## 驗證
 
@@ -127,23 +148,27 @@ InlineEdit 不含 async loading state。若 commit 需要 async 儲存,consumer
 ## A11y 預設
 
 **ARIA**:
-- read 態隱形 Pressable = `<button type="button">`,帶 `aria-label`(預設「編輯 {label}」)——螢幕閱讀器朗讀「可編輯」意圖。
-- read 態語意標籤（`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）。
+- 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**:
-| 鍵 | read 態 | edit 態 |
+| 鍵 | view 態 | edit 態 |
 |----|---------|---------|
-| `Tab` | focus read 按鈕（外框染 `border-primary` 藍框,**非** ring;對齊本 spec 其餘段） | 依控件內部 focus 行為 |
-| `Enter` / `Space` | 進 edit | `Enter` commit |
-| `Esc` | — | cancel(還原不 commit) |
+| `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 分流)」段)。
 
-**Focus 管理**:進 edit 態自動 focus 控件（`autoFocus`);commit/cancel 結算後 focus 返回 read 按鈕(焦點不遺失)。
+## 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)。
 
 ## 禁止事項
 
-- ❌ read 態 hover 用邊框——用 `bg-neutral-hover` 背景 tint（邊框是 edit 態語言）
+- ❌ view 態 hover 用邊框——用 `bg-neutral-hover` 背景 tint（邊框是 edit 態語言）
 - ❌ edit 態手刻 input chrome——用 Field 控件（預設 `<Input>`)
 - ❌ 用 InlineEdit 包 DataTable 密集可編輯格——用 naked cell
 - ❌ 空值顯示唯讀展示的半形 `-` dash——InlineEdit 是可編輯欄位,空值 = placeholder 或空白
-- ❌ read 態語意標籤用 heading 時把它塞進 button——用隱形 Pressable 疊加,保留文件大綱
+- ❌ view 態語意標籤用 heading 時把它塞進 button——用隱形 Pressable 疊加,保留文件大綱
+- ❌ 用 disabled / 灰化表達鎖定——就地編輯無 disabled 態,鎖定 = `editable=false` 純 view 無入口、不灰化(見「editable 閘」)

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

@@ -69,7 +69,7 @@ export const MetadataFields: Story = {
   ),
 }
 
-/* ── 三態 matrix:read / hover / edit（play 驅動 hover + edit 態顯示）── */
+/* ── 狀態 matrix:view / hover / edit（二態 canonical,hover 是 view 子態;play 驅動 hover + edit 態顯示）── */
 function StateRow({
   caption,
   children,
@@ -77,22 +77,23 @@ function StateRow({
 }: { caption: string; children: React.ReactNode } & React.HTMLAttributes<HTMLDivElement>) {
   return (
     <div {...rest}>
-      <p className="mb-2 text-caption text-fg-muted">{caption}</p>
-      {/* px-field-px 抵銷 InlineEdit 的 -mx-field-px,讓文字左緣與說明對齊 */}
-      <div className="px-[var(--field-px)]">{children}</div>
+      {/* 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: '三態:閱讀/懸停/編輯',
+  name: '狀態:檢視/懸停/編輯',
   render: () => (
     <div className="flex w-[440px] flex-col gap-6">
-      <StateRow caption="read(靜態)—— 純文字,透明邊框(預留、不可見)、無底色">
+      <StateRow caption="view(靜止)—— 純值,透明邊框(預留、不可見)、無底色">
         <StatefulInlineEdit value="Design review notes" label="標題" />
       </StateRow>
       <StateRow
-        caption="read + hover —— 灰底 bg-neutral-hover + rounded-md(非邊框)"
+        caption="view + hover —— 灰底 bg-neutral-hover + rounded-md(非邊框)"
         data-testid="inline-edit-hover-row"
       >
         <StatefulInlineEdit value="Design review notes" label="標題" />
@@ -120,10 +121,10 @@ export const States: Story = {
   },
 }
 
-/* ── 真實業務:工作項目 Status 就地編輯(型別化 read = Tag)──
-   SSOT 示範:read 態的 Tag **不是** InlineEdit 自刻,而是渲染 `<Select mode="display" display="tag">`
-   —— 「select 值 → Tag」的格式化 SSOT 住在 Select 的 display mode(= DataTable 格子消費的同一份)。
-   read 與 edit 用同一個 Select、只切 mode,格式零分歧。 */
+/* ── 真實業務:工作項目 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' },
@@ -131,8 +132,8 @@ const STATUS_OPTIONS = [
   { value: 'done', label: 'Done', tagVariant: 'green' },
 ]
 
-// 架構理由(移出 story name,per story-rules.md name 必人話):read 態顯示為 Tag,SSOT = Select
-// 的 display mode —— InlineEdit 委派 Select 控件,read view 消費 Select 的 display 呈現(標籤/色點)。
+// 架構理由(移出 story name,per story-rules.md name 必人話):view 態顯示為 Tag,SSOT = Select
+// 的 view mode —— InlineEdit 委派 Select 控件,view 態消費 Select 的 view 呈現(標籤/色點)。
 export const SelectTagField: Story = {
   name: '狀態就地編輯(讀取時顯示為標籤)',
   render: () => {
@@ -145,13 +146,13 @@ export const SelectTagField: Story = {
           onCommit={setStatus}
           label="status"
           size="sm"
-          // read:Select 的 display mode 輸出 Tag(格式化 SSOT 住在 Select,InlineEdit 不自刻)。
+          // view:Select 的 view mode 輸出 Tag(格式化 SSOT 住在 Select,InlineEdit 不自刻)。
           // Tag **盒子左緣**對齊 label / 其他純文字值,tag 文字被 pill 內距自然縮排 —— 對齊 Meegle 實測
           // (PIL 量測 2026-07-10:Meegle pill box=label 左緣、text 縮排 ~8px@1x)。**不做 text outdent**。
           renderRead={(v) => (
-            <Select mode="display" display="tag" size="sm" value={v} options={STATUS_OPTIONS} />
+            <Select mode="view" display="tag" size="sm" value={v} options={STATUS_OPTIONS} />
           )}
-          // edit:同一個 Select 切 edit mode + 立即開選單;選完即 commit 回 read
+          // edit:同一個 Select 切 edit mode + 立即開選單;選完即 commit 回 view
           renderEdit={(p) => (
             <Select
               autoFocus
@@ -173,7 +174,7 @@ export const SelectTagField: Story = {
 }
 
 /* ── 真實業務:工作項目 Description 多行就地編輯(Jira description 類)──
-   multiline:read 態換行顯示、edit 態預設 Textarea(Enter=換行、Cmd/Ctrl+Enter 或 blur 提交)。 */
+   multiline:view 態換行顯示、edit 態預設 Textarea(Enter=換行、Cmd/Ctrl+Enter 或 blur 提交)。 */
 export const MultilineDescription: Story = {
   name: '多行描述就地編輯(Jira 描述欄類)',
   render: () => {
@@ -198,7 +199,7 @@ export const MultilineDescription: Story = {
 /* ── 真實業務:工作項目詳情面板 —— vertical Field(FieldLabel + control)+ InlineEdit ──
    混合 plain / Tag / 多行欄位,驗證 Tag 值與 FieldLabel + 其他 plain 值的左緣視覺對齊。 */
 export const VerticalFieldForm: Story = {
-  name: '詳情面板:垂直排列 Field + InlineEdit(Tag 對齊)',
+  name: '詳情面板:垂直欄位就地編輯',
   render: () => {
     const [status, setStatus] = React.useState('in-progress')
     const [desc, setDesc] = React.useState('Safari 上點擊結帳時,e2e 測試會間歇性失敗。')
@@ -218,7 +219,7 @@ export const VerticalFieldForm: Story = {
             onCommit={setStatus}
             label="status"
             renderRead={(v) => (
-              <Select mode="display" display="tag" size="sm" value={v} options={STATUS_OPTIONS} />
+              <Select mode="view" display="tag" size="sm" value={v} options={STATUS_OPTIONS} />
             )}
             renderEdit={(p) => (
               <Select