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

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

@@ -0,0 +1,246 @@
+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'],
+}
+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 (
+    <div className="grid grid-cols-[128px_1fr] items-center gap-[var(--layout-space-tight)]">
+      <span className="text-body text-fg-secondary">{label}</span>
+      <StatefulInlineEdit value={value} label={label} placeholder={placeholder} size="sm" />
+    </div>
+  )
+}
+
+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:read / hover / edit（play 驅動 hover + edit 態顯示）── */
+function StateRow({
+  caption,
+  children,
+  ...rest
+}: { 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>
+    </div>
+  )
+}
+
+export const States: Story = {
+  name: '三態:閱讀/懸停/編輯',
+  render: () => (
+    <div className="flex w-[440px] flex-col gap-6">
+      <StateRow caption="read(靜態)—— 純文字,透明邊框(預留、不可見)、無底色">
+        <StatefulInlineEdit value="Design review notes" label="標題" />
+      </StateRow>
+      <StateRow
+        caption="read + 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')
+    // hover 態:滑鼠移入第二列 → 顯示 bg-neutral-hover 灰底
+    const hoverBtn = canvasElement
+      .querySelector('[data-testid="inline-edit-hover-row"]')
+      ?.querySelector('button')
+    if (hoverBtn) await userEvent.hover(hoverBtn)
+    // edit 態:點擊第三列 → 切成真正的 Input 控件
+    const editBtn = canvasElement
+      .querySelector('[data-testid="inline-edit-edit-row"]')
+      ?.querySelector('button')
+    if (editBtn) await userEvent.click(editBtn)
+  },
+}
+
+/* ── 真實業務:工作項目 Status 就地編輯(型別化 read = Tag)──
+   SSOT 示範:read 態的 Tag **不是** InlineEdit 自刻,而是渲染 `<Select mode="display" display="tag">`
+   —— 「select 值 → Tag」的格式化 SSOT 住在 Select 的 display mode(= DataTable 格子消費的同一份)。
+   read 與 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 必人話):read 態顯示為 Tag,SSOT = Select
+// 的 display mode —— InlineEdit 委派 Select 控件,read view 消費 Select 的 display 呈現(標籤/色點)。
+export const SelectTagField: Story = {
+  name: '狀態就地編輯(讀取時顯示為標籤)',
+  render: () => {
+    const [status, setStatus] = React.useState('in-progress')
+    return (
+      <div className="grid w-[440px] grid-cols-[128px_1fr] items-center gap-[var(--layout-space-tight)] rounded-lg border border-border bg-surface p-[var(--layout-space-loose)]">
+        <span className="text-body text-fg-secondary">Status</span>
+        <InlineEdit<string>
+          value={status}
+          onCommit={setStatus}
+          label="status"
+          size="sm"
+          // read:Select 的 display 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} />
+          )}
+          // edit:同一個 Select 切 edit mode + 立即開選單;選完即 commit 回 read
+          renderEdit={(p) => (
+            <Select
+              autoFocus
+              display="tag"
+              size="sm"
+              value={p.value}
+              options={STATUS_OPTIONS}
+              defaultOpen
+              onChange={(next) => {
+                p.onChange(next as string)
+                p.commit()
+              }}
+            />
+          )}
+        />
+      </div>
+    )
+  },
+}
+
+/* ── 真實業務:工作項目 Description 多行就地編輯(Jira description 類)──
+   multiline:read 態換行顯示、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)]">
+        <p className="mb-1 text-caption text-fg-secondary">DESCRIPTION</p>
+        <InlineEdit
+          multiline
+          value={desc}
+          onCommit={setDesc}
+          label="description"
+          placeholder="Add a description…"
+        />
+      </div>
+    )
+  },
+}
+
+/* ── 真實業務:工作項目詳情面板 —— vertical Field(FieldLabel + control)+ InlineEdit ──
+   混合 plain / Tag / 多行欄位,驗證 Tag 值與 FieldLabel + 其他 plain 值的左緣視覺對齊。 */
+export const VerticalFieldForm: Story = {
+  name: '詳情面板:垂直排列 Field + InlineEdit(Tag 對齊)',
+  render: () => {
+    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>
+          <StatefulInlineEdit value="Alex Rivera" label="assignee" />
+        </Field>
+        <Field orientation="vertical">
+          <FieldLabel>Status</FieldLabel>
+          <InlineEdit<string>
+            value={status}
+            onCommit={setStatus}
+            label="status"
+            renderRead={(v) => (
+              <Select mode="display" 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>
+    )
+  },
+}

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

@@ -0,0 +1,287 @@
+// ── 消費的 SSOT ──
+// - components/Field/field-controls.spec.md(「Field 框架地圖」段:InlineEdit = read↔edit 疊在 Field 之上;edit-in-place)
+// - components/Field/field-edit-keys.ts(makeEditSettleKeyHandler = Enter/Esc + 中文 IME guard 結算 SSOT,與 DataTable cell 同源)
+// - 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 態高度)
+// - 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:
+//     https://github.com/pioug/atlassian-frontend-mirror/blob/main/design-system/inline-edit/src/internal/read-view.tsx
+//
+// ── 型別化 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 類欄位。
+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 { makeEditSettleKeyHandler } from '@/design-system/components/Field/field-edit-keys'
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+/** renderEdit 回呼收到的受控介面 —— consumer 換任意 Field 控件(Textarea / Select / DatePicker …)接線用 */
+export interface InlineEditRenderProps<T = string> {
+  /** 目前編輯中的草稿值(內部管理,非已 commit 的 value) */
+  value: T
+  /** 草稿變更 */
+  onChange: (next: T) => void
+  /** 提交草稿 → onCommit(next) + 回 read 態 */
+  commit: () => void
+  /** 放棄草稿 → 回 read 態不 commit */
+  cancel: () => void
+  /** 進 edit 態時自動 focus 控件 */
+  autoFocus: boolean
+  /** 尺寸(cascade 給控件,與 read 態高度對齊) */
+  size: FieldSize
+  /** 控件無障礙標籤(= label prop) */
+  'aria-label'?: string
+}
+
+type ReadTag = 'span' | 'p' | 'div' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
+
+export interface InlineEditProps<T = string> {
+  /** 已提交的欄位值(read 態顯示;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)。
+   */
+  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(見檔頭)。
+   */
+  renderRead?: (value: T) => React.ReactNode
+  /** 多行欄位(Jira description 類):read 態換行 + 預設 edit 態用 `<Textarea>`,Enter=換行、Cmd/Ctrl+Enter 或 blur 提交 */
+  multiline?: boolean
+  /** 欄位人類可讀名稱 —— 組 read 按鈕 aria-label(「編輯 {label}」)+ 控件 aria-label */
+  label?: string
+  /** 空值時 read 態顯示的提示文字(fg-muted) */
+  placeholder?: string
+  /** 尺寸 —— read 態最小高度 + 預設 Input 尺寸(與 Field 家族一致) */
+  size?: FieldSize
+  /** read 態語意標籤(標題場景傳 'h1'/'h2' 維持文件大綱;預設 'span') */
+  as?: ReadTag
+  /** read 態文字樣式(如標題 `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>)
+ *
+ * 互動模型 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 按鈕
+ * - **鍵盤結算**:消費 `makeEditSettleKeyHandler`(含中文 IME guard,與 DataTable cell 同源)
+ *
+ * read 態用隱形 Pressable(絕對定位 `<button>` 疊於內容上)—— 讓 `as="h1"` 等標題標籤保留文件大綱
+ * a11y,同時提供鍵盤 focus + Enter 進 edit(HTML 內容模型不允許 heading 巢狀於 button,故分離)。
+ */
+function InlineEditImpl<T = string>(
+  {
+    value,
+    onCommit,
+    renderEdit,
+    renderRead,
+    multiline = false,
+    label,
+    placeholder,
+    size = 'sm',
+    as = 'span',
+    readClassName,
+    className,
+  }: InlineEditProps<T>,
+  ref: React.Ref<HTMLDivElement>,
+) {
+  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:焦點不遺失)
+  const returnFocusRef = React.useRef(false)
+  const readButtonRef = React.useRef<HTMLButtonElement>(null)
+
+  const setDraftValue = React.useCallback((next: T) => {
+    draftRef.current = next
+    setDraft(next)
+  }, [])
+
+  const enterEdit = React.useCallback(() => {
+    finalizedRef.current = false
+    setDraftValue(value)
+    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])
+
+  const cancel = React.useCallback(() => {
+    if (finalizedRef.current) return
+    finalizedRef.current = true
+    returnFocusRef.current = true
+    setEditing(false)
+  }, [])
+
+  // 結算後把 focus 送回 read 按鈕(所有結算路徑含 blur / Enter / Esc 皆 return —— commit/cancel
+  // 一律 set returnFocusRef=true;對齊 spec「任一路徑結算後 focus 送回 read 按鈕」L39/L141「焦點不遺失」)
+  React.useEffect(() => {
+    if (!editing && returnFocusRef.current) {
+      returnFocusRef.current = false
+      readButtonRef.current?.focus()
+    }
+  }, [editing])
+
+  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)
+
+  if (editing) {
+    const editProps: InlineEditRenderProps<T> = {
+      value: draft,
+      onChange: setDraftValue,
+      commit,
+      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。
+    const defaultEditNode = multiline ? (
+      <Textarea
+        autoFocus
+        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 })}
+      />
+    ) : (
+      <Input
+        autoFocus
+        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 })}
+      />
+    )
+    const editNode = renderEdit ? renderEdit(editProps) : defaultEditNode
+    return (
+      <div ref={ref} data-editing={editing} className={rootClass}>
+        {editNode}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      ref={ref}
+      data-editing={editing}
+      // 外框(rootClass 幾何)+ read chrome(inlineEditReadStyles:border 預留 / px / min-h / hover 底色 / focus 藍框)
+      className={cn(rootClass, inlineEditReadStyles({ size, multiline }))}
+    >
+      {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>
+      )}
+      {/* 隱形 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>
+  )
+}
+
+// 泛型 forwardRef:forwardRef 不原生支援泛型,以 cast 還原公開型別(標準 workaround)。
+const InlineEdit = React.forwardRef(InlineEditImpl) as (<T = string>(
+  props: InlineEditProps<T> & { ref?: React.Ref<HTMLDivElement> },
+) => React.ReactElement) & { displayName?: string }
+InlineEdit.displayName = 'InlineEdit'
+
+export { InlineEdit }

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

@@ -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 Ⅰ）+ 文字正常色，空值顯示 —（em dash）',
+  display:  '純展示資料 — 無 chrome（transparent + !px-0 !py-0 零內距，field-wrapper.tsx Path Ⅰ）+ 文字正常色，空值顯示半形 -（hyphen，同 value 前景色）',
   readonly: '不可編輯但可見 — bg-readonly(neutral-2) + 無邊框 + 文字正常色',
   disabled: '被停用的欄位 — bg-disabled(neutral-2) + 無邊框 + 文字灰化',
 }
@@ -211,8 +211,9 @@ export const Overview = {
           {MODES.map((m) => (
             <div key={m} className="flex items-center gap-4">
               <div className="w-64 shrink-0">
-                {/* display mode 讀 value(非 defaultValue)渲染 <span>;其餘 mode 用 defaultValue 保持 uncontrolled */}
-                {m === 'display' ? (
+                {/* display + readonly 讀 controlled value:兩者「空值」皆走 <span> 顯 '-'(input.tsx:121),
+                    demo 要展示有值狀態故傳 value;edit / disabled 用 defaultValue 保持 uncontrolled */}
+                {(m === 'display' || m === 'readonly') ? (
                   <Input mode={m} value="Wireless Bluetooth Headphones" size="md" />
                 ) : (
                   <Input mode={m} defaultValue="Wireless Bluetooth Headphones" size="md" />
@@ -242,7 +243,7 @@ export const Overview = {
             <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' | 'bare'", "'default'", '視覺 chrome（正交於 mode）；bare = 透明、hover/focus 才出現 border，用於 toolbar inline editing'],
+                ['variant', "'default'", "'default'", '視覺 chrome（正交於 mode；公開型別僅 default，2026-07-14 收窄）；naked = 無 chrome，host cell 提供 border/focus（@internal cell-as-input）；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'],
@@ -698,11 +699,11 @@ export const StateBehavior = {
           </div>
         </div>
 
-        {/* Click-through behavior */}
+        {/* startIcon pointer-events (non-intercepting) */}
         <div className="flex flex-col gap-4">
-          <span className="text-caption font-medium text-fg-secondary">點擊穿透 — startIcon pointer-events-none</span>
+          <span className="text-caption font-medium text-fg-secondary">startIcon 不攔截點擊 — pointer-events-none</span>
           <div className="flex flex-col gap-2 max-w-sm">
-            <span className="text-[11px] text-fg-muted">點擊 icon 區域，focus 穿透到 input。endAction 有自己的點擊行為，不穿透。</span>
+            <span className="text-[11px] text-fg-muted">startIcon（SVG）帶 pointer-events-none，不攔截點擊、不擋文字選取（不成為死區）。注意：點 icon 區域**不會** focus input（icon 與 input 為 sibling，無 click-to-focus）。endAction 是互動元素，有自己的點擊行為。</span>
             <Input
               startIcon={Search}
               value={query}

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

@@ -60,16 +60,6 @@ export const UsageGuidance: Story = {
       </Section>
 
       <Section title="何時不用 + 替代方案">
-        <Rule
-          title="❌ 不用 Input variant='bare' 在表單主區域"
-          note="bare 是 toolbar inline edit 專用(適合外層已有 affordance)。表單需要明確 field chrome → 用 variant='default'。Notion 的 property inline edit 用 bare"
-        >
-          <div>
-            <Input variant="bare" placeholder="搜尋..." />
-            <Label warn>❌ 表單用 default,bare 只用 toolbar</Label>
-          </div>
-        </Rule>
-
         <Rule
           title="❌ 不用 Input startIcon 表達狀態(有效 / 無效)"
           note="startIcon 是「欄位用途」識別符(郵件、搜尋、網址)。狀態用邊框 + help text。Stripe 信卡欄的有效狀態由邊框顏色傳達"
@@ -119,7 +109,7 @@ export const ModeRule: Story = {
         title="readonly — 表單中顯示但當下不可編輯"
         note="同 edit 高度(neutral-2 底色、無邊框),確保與其他欄位並排對齊。常見場景:viewing mode、送出後鎖定但仍在表單脈絡"
       >
-        <Input mode="readonly" defaultValue="alice@example.com" />
+        <Input mode="readonly" value="alice@example.com" />
       </Rule>
 
       <Rule
@@ -140,7 +130,7 @@ export const ModeRule: Story = {
         title="❌ 不用 readonly 作為 DataTable cell"
         note="readonly 仍然有 padding + 視覺 chrome,密集列表會顯得鬆散。Table cell 用 `<Input mode='display'>`(零視覺 chrome、無左右 padding;wrapper 高度同 readonly)"
       >
-        <Input mode="readonly" defaultValue="alice@example.com" />
+        <Input mode="readonly" value="alice@example.com" />
         <Label warn>↑ 在 table cell 中會過高且有多餘 padding → 用 &lt;Input mode=&quot;display&quot; /&gt;</Label>
       </Rule>
     </div>