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

package/src/components/FileViewer/image-renderer.tsx

@@ -4,6 +4,7 @@ import {
   TransformWrapper,
   TransformComponent,
   type ReactZoomPanPinchRef,
+  type ReactZoomPanPinchContentRef,
 } from 'react-zoom-pan-pinch'
 import type { FileRendererProps } from './file-viewer-types'
 
@@ -41,7 +42,7 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
   fitRequest,
   onCapabilitiesChange,
 }) => {
-  const apiRef = React.useRef<ReactZoomPanPinchRef | null>(null)
+  const apiRef = React.useRef<ReactZoomPanPinchContentRef | null>(null)
   const imgRef = React.useRef<HTMLImageElement | null>(null)
   const containerRef = React.useRef<HTMLDivElement | null>(null)
   const [loaded, setLoaded] = React.useState(false)
@@ -123,12 +124,38 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
     const container = containerRef.current
     if (!container) return
     let rafId = 0
+    // manual mode 視覺中心保持需要前次容器尺寸(比對 delta 反推新 position)
+    let prevW = container.clientWidth
+    let prevH = container.clientHeight
     const obs = new ResizeObserver(() => {
       if (rafId) cancelAnimationFrame(rafId)
       rafId = requestAnimationFrame(() => {
         rafId = 0
         const mode = lastFitModeRef.current
-        if (mode === 'manual') return
+        const newW = container.clientWidth
+        const newH = container.clientHeight
+        if (mode === 'manual') {
+          // 2026-07-08 Q2 補洞(user「畫布在各種情況都能完美適應」):manual zoom 下容器 resize
+          //(InfoPanel 開合 / Filmstrip 增減 / 視窗 RWD / 裝置旋轉 — 同一咽喉點全涵蓋)
+          // = **scale 不變、視覺中心點保持**(Figma / Photoshop canonical;原本 early-return
+          // 什麼都不做 → transform 座標絕對值,容器變窄內容偏移)。
+          // 幾何:舊容器中心對到的內容點 (cx,cy),resize 後把同一內容點放到新容器中心。
+          const api = apiRef.current
+          if (api && (newW !== prevW || newH !== prevH)) {
+            const { positionX, positionY, scale } = api.state
+            const cx = (prevW / 2 - positionX) / scale
+            const cy = (prevH / 2 - positionY) / scale
+            programmaticZoomRef.current = true
+            api.setTransform(newW / 2 - cx * scale, newH / 2 - cy * scale, scale, 0)
+            // setTransform 同步無動畫;下一 frame 解 flag(防 onTransform 誤標 manual→已是 manual,保守處理)
+            requestAnimationFrame(() => { programmaticZoomRef.current = false })
+          }
+          prevW = newW
+          prevH = newH
+          return
+        }
+        prevW = newW
+        prevH = newH
         const scale = computeFitScale(mode)
         if (scale == null) return
         onZoomChange(clampToPct(scale))
@@ -196,8 +223,8 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
   return (
     <div ref={containerRef} className="w-full h-full overflow-hidden" onDoubleClick={handleDoubleClick}>
       <TransformWrapper
-        // any-allow: react-zoom-pan-pinch TransformWrapper ref type not exported; API surface stable per lib docs
-        ref={apiRef as any}
+        // TransformWrapper ref = ReactZoomPanPinchContentRef(dist/index.d.ts:351 + export L399);型別有 export → 用真型別,不需 as any
+        ref={apiRef}
         initialScale={1}
         minScale={MIN_SCALE}
         maxScale={MAX_SCALE}
@@ -211,9 +238,10 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
         // Wheel zoom canonical:
         // - `step: 0.03` = 每 tick ~3% scale,對齊 Figma / Preview.app 細緻度
         //   (原 0.1 = 10% 太粗,接近 Google Slides 離散慣例)
-        // - multiplicative 等距:library 內部 scale factor 乘算,log 視覺等距
-        // 註:原本用 `smoothStep: 0.005` 但當前 lib type 不含該 key;若需 trackpad 細緻,
-        // 升級 react-zoom-pan-pinch 到有此 prop 的版本或切到 `smoothScroll` API
+        // - wheel zoom = `scale + delta × step` 加法線性(handleCalculateWheelZoom,
+        //   dist/index.esm.js:1265;非 multiplicative/log —— 乘算 exp 只用於 setup smooth 的按鈕 zoom path)
+        // 註:lib 型別無 `smoothStep` / `smoothScroll` key(僅 setup `smooth?:boolean` 走按鈕 exp、
+        // 不影響 wheel);trackpad 平滑度目前無對應 wheel prop 可調
         wheel={{ step: 0.03 }}
         // Q3 雙擊改自定 handler:lib `mode: 'reset'` 永遠 reset 到 initialScale=1 → 100%,
         // 失去 fit ↔ 100% toggle UX(Apple Photos / Drive canonical)。disabled lib 預設 + 自定 onDoubleClick。

package/src/components/HoverCard/hover-card.anatomy.stories.tsx

@@ -4,6 +4,10 @@
 //   shadow / padding / size 全由 consumer 透過 className 決定;無 own variant /
 //   state / size。Overview + VisualVariants 兩個 story 已涵蓋 consumer 兩種
 //   常見視覺(ProfileCard 亮色 vs OverflowIndicator 深色 tooltip)。
+// @story-trait-allow: missing-opensnapshot — 同 hover-card.stories.tsx 檔頭 rationale:
+//   hover-trigger 行為 primitive 的 anatomy doc 內多個 inline hover demo,forced defaultOpen
+//   會讓多張浮層互疊蓋住規格表;open-state 視覺快照由 consumer canonical(ProfileCard /
+//   OverflowIndicator)各自的 OpenSnapshot 涵蓋。
 import type { Meta, StoryObj } from '@storybook/react'
 import { HoverCard, HoverCardTrigger, HoverCardContent } from './hover-card'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
@@ -27,7 +31,7 @@ export const Overview: Story = {
         <div className="flex items-center gap-6">
           <HoverCard>
             <HoverCardTrigger asChild>
-              <Avatar alt="Ada Chen" size={40} />
+              <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada Chen" size={40} />
             </HoverCardTrigger>
             <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-4 shadow-[var(--elevation-200)]">
               <div className="flex flex-col gap-2 w-56">
@@ -139,7 +143,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"ARIA 與互動模式:Radix HoverCard 刻意不設角色語意 / aria-* 屬性(定位為 sighted-mouse-user 增強,卡片內容不暴露給輔助技術),只提供 hover / focus 開、Esc 關 + data-state。觸發元素的可聚焦性需 consumer 自補(例如 Avatar 的 hoverCard 在元件內手動加 tabIndex=0 + role=\"button\" + aria-haspopup=\"dialog\")。\n\n鍵盤操作:\n\n- Tab — 焦點移到觸發元素\n- Hover 或 focus — 開啟浮層卡片\n- Esc — 關閉卡片\n\n焦點行為:這是非阻斷(non-modal)的浮層,focus 會開啟卡片但不會把焦點鎖在裡面;焦點仍留在觸發元素,按 Esc 即可關閉。觸發元素 focus 時顯示可見的外框(2px 實線,使用 --ring 色),與整個設計系統的 focus-visible 樣式一致。\n\n鍵盤限制:Radix HoverCard 會把卡片內所有可 Tab 的節點強制設成 tabindex=\"-1\",因此卡片內部的按鈕 / 連結鍵盤 Tab 到不了 — 鍵盤使用者僅能 focus 觸發元素開卡 + Esc 關卡,無法進入卡片操作互動內容。關鍵互動勿放 HoverCard 內,需鍵盤可達的互動浮層請用 Popover(click 觸發)。\n\n驗證:Storybook 無障礙檢測面板應為 0 項嚴重違規;文字對比至少 4.5:1、UI 元素對比至少 3:1,符合 WCAG AA。"}</p>
+      <p className="whitespace-pre-line">{"ARIA 與互動模式:Radix HoverCard 刻意不設角色語意 / aria-* 屬性(定位為 sighted-mouse-user 增強,卡片內容不暴露給輔助技術),只提供 hover / focus 開、Esc 關 + data-state。觸發元素的可聚焦性需 consumer 自補(例如 Avatar 的 hoverCard 在元件內手動加 tabIndex=0 + role=\"img\" + aria-label;2026-07-06 拆除 role=\"button\" / aria-haspopup=\"dialog\" 空承諾 — 無 Enter/Space 行為卻宣告 popup ARIA = 對輔助技術的假承諾,對齊 avatar.tsx:252-256 + hover-card.spec.md:144)。\n\n鍵盤操作:\n\n- Tab — 焦點移到觸發元素\n- Hover 或 focus — 開啟浮層卡片\n- Esc — 關閉卡片\n\n焦點行為:這是非阻斷(non-modal)的浮層,focus 會開啟卡片但不會把焦點鎖在裡面;焦點仍留在觸發元素,按 Esc 即可關閉。觸發元素 focus 時顯示可見的外框(2px 實線,使用 --ring 色),與整個設計系統的 focus-visible 樣式一致。\n\n鍵盤限制:Radix HoverCard 會把卡片內所有可 Tab 的節點強制設成 tabindex=\"-1\",因此卡片內部的按鈕 / 連結鍵盤 Tab 到不了 — 鍵盤使用者僅能 focus 觸發元素開卡 + Esc 關卡,無法進入卡片操作互動內容。關鍵互動勿放 HoverCard 內,需鍵盤可達的互動浮層請用 Popover(click 觸發)。\n\n驗證:Storybook 無障礙檢測面板應為 0 項嚴重違規;文字對比至少 4.5:1、UI 元素對比至少 3:1,符合 WCAG AA。"}</p>
     </div>
   ),
 }

package/src/components/HoverCard/hover-card.principles.stories.tsx

@@ -1,6 +1,9 @@
 // @principles-rationale: Merged WhenToUse + VsTooltipRule + NotForCriticalInfoRule
 // into a single `UsageGuidance` story (3 sections) per 2026-04-26 user mandate to
 // consolidate decision-related stories. PureBehaviorPrimitiveRule kept as separate principle.
+// @story-trait-allow: missing-opensnapshot — 同 hover-card.stories.tsx 檔頭 rationale:
+// 原則頁多個 inline hover demo,forced defaultOpen 會多張浮層互疊;open-state 快照由
+// consumer canonical(ProfileCard / OverflowIndicator)的 OpenSnapshot 涵蓋。
 import React from 'react'
 import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'
@@ -121,7 +124,7 @@ export const UsageGuidance: Story = {
             <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-4 shadow-[var(--elevation-200)]">
               <div className="flex flex-col gap-2 w-64">
                 <div className="flex items-center gap-3">
-                  <Avatar alt="Ada Chen" size={40} />
+                  <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada Chen" size={40} />
                   <div>
                     <div className="text-body font-medium">Ada Chen</div>
                     <div className="text-caption text-fg-muted">Design Engineer</div>
@@ -149,7 +152,7 @@ export const UsageGuidance: Story = {
             <div className="flex flex-col gap-1">
               <HoverCard>
                 <HoverCardTrigger asChild>
-                  <Avatar alt="Ada Chen" size={32} />
+                  <Avatar src="https://i.pravatar.cc/64?u=ada-chen" alt="Ada Chen" size={32} />
                 </HoverCardTrigger>
                 <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-3">
                   <div className="flex flex-col gap-2 w-56">
@@ -206,7 +209,7 @@ export const PureBehaviorPrimitiveRule: Story = {
         note="人員類 Avatar 透過 `hoverCard` prop 自動 wrap HoverCardTrigger,不需要 consumer 手動組合。統一人員 hover 提供 ProfileCard 的體驗"
       >
         <div className="flex items-center gap-3">
-          <Avatar alt="Ada Chen" size={40} hoverCard={
+          <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada Chen" size={40} hoverCard={
             <div className="flex flex-col gap-2 w-56">
               <div className="text-body font-medium">Ada Chen</div>
               <div className="text-caption text-fg-muted">Design Engineer · 台北</div>

package/src/components/HoverCard/hover-card.spec.md

@@ -19,10 +19,10 @@ Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
 
 **實作基礎**：基於 Radix HoverCard——純行為 primitive，只提供觸發邏輯、定位、動畫，不含視覺樣式。
 
-**分類**：Internal primitive——consumer 不直接 import;由 Avatar(`hoverCard`)/ OverflowIndicator / ProfileCard 場景組合消費(frontmatter `isInternal`:root barrel 排除,storybook `Design System/Internal/HoverCard`)。
+**分類**：Internal primitive——不進 root barrel front-door、不裸用;DS 內由 Avatar(`hoverCard`)/ OverflowIndicator / ProfileCard 場景組合消費;consumer 需要時可經 per-component subpath 包裝並自行確認後使用(`.claude/rules/ui-development.md`「Root barrel front-door 排除」SSOT,internal ≠ 禁用)(frontmatter `isInternal`:root barrel 排除,storybook `Design System/Internal/HoverCard`)。
 
-- **是**：hover 顯示可互動內容（按鈕、連結、可選取文字）的浮層容器
-- **不是**：Tooltip（純文字提示、不可互動、hover 離開即消失）
+- **是**：hover 顯示可互動內容（按鈕、連結、可選取文字——**滑鼠互動**；鍵盤進不了卡片，見「A11y 預設」）的浮層容器，定位為滑鼠 / focus 使用者的補充閱讀 surface
+- **不是**：Tooltip（純文字提示、不可互動、hover 離開即消失）；也不是鍵盤可操作的互動浮層（那是 Popover）
 
 **Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
 
@@ -53,12 +53,12 @@ Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
 | | HoverCard | Tooltip |
 |---|---|---|
 | 觸發 | hover | hover |
-| **內容可互動** | 是（按鈕、連結、hover 子元素） | 否（純文字） |
+| **內容可互動** | 是——限滑鼠（Radix 設 content 內 tabbable node 為 `tabindex="-1"`，鍵盤不可達，見「A11y 預設」） | 否（純文字） |
 | 停留行為 | 滑鼠移到浮層上不消失 | 滑鼠離開 trigger 即消失 |
 | 視覺樣式 | 由 consumer 決定（亮色 card 或深色 tooltip 風格皆可） | 統一深色背景 |
 | 典型用例 | ProfileCard、內容預覽、溢出清單 | icon 用途、shortcut、截斷文字補全 |
 
-**Fallback**：需要放按鈕 / 連結 → HoverCard；一句話純文字 → Tooltip。
+**Fallback**：需要放按鈕 / 連結（滑鼠增強）→ HoverCard；鍵盤必須可操作的互動浮層 → Popover；一句話純文字 → Tooltip。
 
 **本節是 HoverCard vs Tooltip 的 SSOT**，Tooltip spec 指回本節。
 

package/src/components/HoverCard/hover-card.stories.tsx

@@ -11,7 +11,7 @@ import { HoverCard, HoverCardTrigger, HoverCardContent } from './hover-card'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
 import { Button } from '@/design-system/components/Button/button'
 import { ProfileCard } from '@/design-system/components/ProfileCard/profile-card'
-import { HOVER_DELAY_RICH_MS, HOVER_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
+import { MOTION_DELAY_RICH_MS, MOTION_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
 
 const meta: Meta = {
   title: 'Design System/Internal/HoverCard/展示',
@@ -45,7 +45,7 @@ export const PersonProfileCard: Story = {
         <HoverCard>
           <HoverCardTrigger asChild>
             <button type="button" aria-label="Ada Chen 個人資訊" className="cursor-pointer rounded-full">
-              <Avatar alt="Ada Chen" color="indigo" size={28} />
+              <Avatar src="https://i.pravatar.cc/56?u=ada-chen" alt="Ada Chen" color="indigo" size={28} />
             </button>
           </HoverCardTrigger>
           <HoverCardContent
@@ -54,7 +54,7 @@ export const PersonProfileCard: Story = {
           >
             <ProfileCard
               name="Ada Chen"
-              avatar={{ alt: 'Ada Chen', color: 'indigo' }}
+              avatar={{ src: 'https://i.pravatar.cc/80?u=ada-chen', alt: 'Ada Chen', color: 'indigo' }}
               subtitle="Design Engineer · Frontend"
               status="online"
               statusMessage="正在處理 login 頁重構"
@@ -130,9 +130,9 @@ export const OverflowList: Story = {
   name: '溢出清單',
   render: () => {
     const hidden = [
-      { name: '黃怡君', color: 'turquoise' as const },
-      { name: '王文彬', color: 'purple' as const },
-      { name: '李思妤', color: 'yellow' as const },
+      { name: '黃怡君', color: 'turquoise' as const, avatarUrl: 'https://i.pravatar.cc/40?u=huang-yijun' },
+      { name: '王文彬', color: 'purple' as const, avatarUrl: 'https://i.pravatar.cc/40?u=wang-wenbin' },
+      { name: '李思妤', color: 'yellow' as const, avatarUrl: 'https://i.pravatar.cc/40?u=li-siyu' },
     ]
     return (
       <div className="flex flex-col gap-3 max-w-md">
@@ -140,10 +140,10 @@ export const OverflowList: Story = {
           此樣式由 OverflowIndicator 使用(深色 tooltip-style)—— +N hover 看完整清單。
         </p>
         <div className="flex items-center gap-1">
-          <Avatar alt="Ada Chen" color="indigo" size={24} />
-          <Avatar alt="張美真" color="magenta" size={24} />
-          <Avatar alt="林伯彥" color="green" size={24} />
-          <HoverCard openDelay={HOVER_DELAY_RICH_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
+          <Avatar src="https://i.pravatar.cc/48?u=ada-chen" alt="Ada Chen" color="indigo" size={24} />
+          <Avatar src="https://i.pravatar.cc/48?u=zhang-meizhen" alt="張美真" color="magenta" size={24} />
+          <Avatar src="https://i.pravatar.cc/48?u=lin-boyan" alt="林伯彥" color="green" size={24} />
+          <HoverCard openDelay={MOTION_DELAY_RICH_MS} closeDelay={MOTION_DELAY_CLOSE_MS}>
             <HoverCardTrigger asChild>
               <button
                 type="button"
@@ -159,7 +159,7 @@ export const OverflowList: Story = {
               <div className="flex flex-col gap-1 min-w-[160px]">
                 {hidden.map((p) => (
                   <div key={p.name} className="flex items-center gap-2 text-caption">
-                    <Avatar alt={p.name} color={p.color} size={20} />
+                    <Avatar src={p.avatarUrl} alt={p.name} color={p.color} size={20} />
                     <span>{p.name}</span>
                   </div>
                 ))}
@@ -247,10 +247,10 @@ export const TriggerShowcase: Story = {
       <div className="flex items-center gap-6 flex-wrap">
         <div className="flex flex-col gap-2">
           <span className="text-footnote text-fg-muted font-mono">trigger: Avatar</span>
-          <HoverCard openDelay={HOVER_DELAY_RICH_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
+          <HoverCard openDelay={MOTION_DELAY_RICH_MS} closeDelay={MOTION_DELAY_CLOSE_MS}>
             <HoverCardTrigger asChild>
               <button type="button" aria-label="Ada Chen 個人資訊" className="cursor-pointer rounded-full">
-                <Avatar alt="Ada Chen" color="indigo" size={32} />
+                <Avatar src="https://i.pravatar.cc/64?u=ada-chen" alt="Ada Chen" color="indigo" size={32} />
               </button>
             </HoverCardTrigger>
             <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-3">
@@ -261,7 +261,7 @@ export const TriggerShowcase: Story = {
 
         <div className="flex flex-col gap-2">
           <span className="text-footnote text-fg-muted font-mono">trigger: Button</span>
-          <HoverCard openDelay={HOVER_DELAY_RICH_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
+          <HoverCard openDelay={MOTION_DELAY_RICH_MS} closeDelay={MOTION_DELAY_CLOSE_MS}>
             <HoverCardTrigger asChild>
               <Button variant="tertiary" size="sm">
                 查看位置
@@ -278,7 +278,7 @@ export const TriggerShowcase: Story = {
 
         <div className="flex flex-col gap-2">
           <span className="text-footnote text-fg-muted font-mono">trigger: text link</span>
-          <HoverCard openDelay={HOVER_DELAY_RICH_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
+          <HoverCard openDelay={MOTION_DELAY_RICH_MS} closeDelay={MOTION_DELAY_CLOSE_MS}>
             <HoverCardTrigger asChild>
               <a
                 href="#"
@@ -296,7 +296,7 @@ export const TriggerShowcase: Story = {
       </div>
 
       <div className="text-footnote text-fg-muted">
-        預設 delay 已內建(<code className="font-mono mx-1">HOVER_DELAY_RICH_MS / HOVER_DELAY_CLOSE_MS</code> SSOT),特殊 tier 才需 override
+        預設 delay 已內建(<code className="font-mono mx-1">MOTION_DELAY_RICH_MS / MOTION_DELAY_CLOSE_MS</code> SSOT),特殊 tier 才需 override
         (motion.spec.md,當前 700ms / 200ms)——避免 hover 過路誤觸發 fetch waterfall;close 延遲讓 user 誤滑出可回來。
       </div>
     </div>

package/src/components/HoverCard/hover-card.tsx

@@ -7,7 +7,8 @@ import * as HoverCardPrimitive from "@radix-ui/react-hover-card"
 
 import { cn } from "@/lib/utils"
 import { OVERLAY_SIDE_OFFSET } from "@/design-system/tokens/elevation/overlay-geometry"
-import { HOVER_DELAY_RICH_MS, HOVER_DELAY_CLOSE_MS } from "@/design-system/tokens/motion/motion"
+import { MOTION_DELAY_RICH_MS, MOTION_DELAY_CLOSE_MS } from "@/design-system/tokens/motion/motion"
+import { overlayMotion } from "@/design-system/tokens/motion/overlay-motion"
 
 /**
  * HoverCard — hover 顯示可互動內容的浮層（行為 primitive）
@@ -25,7 +26,7 @@ import { HOVER_DELAY_RICH_MS, HOVER_DELAY_CLOSE_MS } from "@/design-system/token
 // (rich 700ms open / close 200ms)— 對齊 tooltip.tsx 同 pattern(2026-05-18 拍板 #3A)。
 // 原裸用 Radix 預設 open 700 / close 300:open 巧合同值、close 300 ≠ canonical 200(drift)。
 // Consumer 仍可 per-instance override(Avatar 同值傳入、OverflowIndicator 傳 plain)。
-const HoverCard = ({ openDelay = HOVER_DELAY_RICH_MS, closeDelay = HOVER_DELAY_CLOSE_MS, ...props }: React.ComponentProps<typeof HoverCardPrimitive.Root>) => (
+const HoverCard = ({ openDelay = MOTION_DELAY_RICH_MS, closeDelay = MOTION_DELAY_CLOSE_MS, ...props }: React.ComponentProps<typeof HoverCardPrimitive.Root>) => (
   <HoverCardPrimitive.Root openDelay={openDelay} closeDelay={closeDelay} {...props} />
 )
 
@@ -56,7 +57,8 @@ const HoverCardContent = React.forwardRef<
         "max-h-[var(--radix-hover-card-content-available-height,100vh)] flex flex-col overflow-hidden min-h-0",
         // 2026-07-05 補 motion-reduce 豁免:對齊 overlay 家族 canonical(popover.tsx / dialog.tsx /
         // dropdown-menu.tsx / tooltip.tsx 同位置寫法)— prefers-reduced-motion 下停用進出場動畫。
-        "data-[state=open]:animate-in data-[state=closed]:animate-out motion-reduce:animate-none",
+        overlayMotion,
+        "data-[state=open]:animate-in data-[state=closed]:animate-out",
         "data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
         "data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
         "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2",

package/src/components/InlineEdit/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 './inline-edit'

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

@@ -0,0 +1,149 @@
+---
+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
+---
+
+# InlineEdit 設計原則
+
+**Layout Family**:composite。**edit 態委派 Family 4（Field Control Layout）**——直接渲染 Field 控件（預設 `<Input>`），幾何/邊框/focus 全繼承 `fieldWrapperStyles`，不新增 layout primitive。**read 態為 self-contained 純文字承載 + 隱形 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 控件回答「這個值長什麼樣、怎麼編輯」;InlineEdit 回答「這個值平常是純文字,想改時才變成 Field 控件」**。
+
+## 互動模型（read / hover / edit 三態 canonical）
+
+| 態 | 視覺 | 行為 |
+|----|------|------|
+| **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 |
+
+**退出 edit 態**:
+- **blur**（點外面）→ `commit`（草稿有變更才觸發 `onCommit`）
+- **Enter** → `commit`
+- **Esc** → `cancel`（放棄草稿,還原 read 態,不 commit）
+- 任一路徑結算後,focus 送回 read 按鈕(鍵盤焦點不遺失)
+
+## 幾何典範（2026-07-09 user 拍板,每值消費既有 SSOT,零自創）
+
+| 面向 | 定義 | 消費的 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 |
+
+**「底色範圍 = 輸入框範圍」不變量**:read 與 edit 兩態共用同一外框幾何（同 `-mx`+calc 寬、同 `min-h`=field-height、同 1px 邊框盒),故 hover 底色與 edit 輸入框逐 pixel 對齊、態切換零位移。（舊版 read 外框 `w-full`+`-mx` 疊加 → 右側短一截、整塊左偏,已修。）
+
+**尺寸預設 = `sm`**（2026-07-09 user 拍板）:read 態無邊框、視覺即純文字,尺寸過大會使版面鬆散;consumer 可傳 `size` 覆寫,標題場景另用 `readClassName` 疊大字級。
+
+**核心不變量:read 態 hover = 背景 tint;read 態 focus = Field 藍框（`border-primary`）,與 edit 態同源。** hover（滑鼠懸停）用底色、focus（鍵盤選中）用藍框——藍框是 edit focus 的預覽,read→edit 一路都是藍框、不會 ring→框跳一下;靜態（無 hover/focus）則透明邊框不可見 = 純文字。
+
+## 型別化 read 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 |
+| `renderEdit?(props)` | edit 態控件 | `multiline`→`<Textarea>` / 否則 `<Input>` | 非 string 值必傳（預設路徑僅 string） |
+| `multiline?` | 多行（Jira description 類） | false | read `items-start` 換行、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`。
+
+**鍵盤結算 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 | 鍵盤 |
+|----|---------|-----------------|---------|------|
+| **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。
+
+**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 語言。
+
+**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」的預設。
+
+**狀態 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 控件(表單本來就是編輯情境,不需要 read 態偽裝成純文字)。
+- **DataTable 密集可編輯格** → 用 naked cell(host cell 自管 border + focus、hover outline affordance;見 `field-controls.spec.md`「Cell(naked variant)」),不是每格包一個 InlineEdit 狀態機。
+- **一律唯讀展示**(不可編) → 用 `<Input mode="display">` / 純文字,不需要 Pressable。
+- **多欄位一次編輯** → 用表單(進入一次編輯全部欄位),不是逐欄 inline edit。
+
+## 近親分界
+
+| 元件 | 分界 |
+|------|------|
+| **Field 控件**（Input/Select/Textarea…） | 一直可編輯的輸入框;InlineEdit 讓它「平常是純文字,想改才現身」 |
+| **`<Input mode="display">`** | 純展示(無互動、不可編);InlineEdit 的 read 態可點擊進 edit |
+| **naked cell**（DataTable） | 表格密集網格的 cell-as-input,host cell 自管 chrome;InlineEdit 是單一 standalone 欄位的閱讀↔編輯 toggle |
+
+## 常見誤解
+
+- **「read 態 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 是唯讀展示語言。）
+
+## 驗證
+
+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**:
+- 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）。
+- edit 態控件帶 `aria-label`（= `label`）。
+
+**Keyboard**:
+| 鍵 | read 態 | edit 態 |
+|----|---------|---------|
+| `Tab` | focus read 按鈕（外框染 `border-primary` 藍框,**非** ring;對齊本 spec 其餘段） | 依控件內部 focus 行為 |
+| `Enter` / `Space` | 進 edit | `Enter` commit |
+| `Esc` | — | cancel(還原不 commit) |
+
+**Focus 管理**:進 edit 態自動 focus 控件（`autoFocus`);commit/cancel 結算後 focus 返回 read 按鈕(焦點不遺失)。
+
+## 禁止事項
+
+- ❌ read 態 hover 用邊框——用 `bg-neutral-hover` 背景 tint（邊框是 edit 態語言）
+- ❌ edit 態手刻 input chrome——用 Field 控件（預設 `<Input>`)
+- ❌ 用 InlineEdit 包 DataTable 密集可編輯格——用 naked cell
+- ❌ 空值顯示唯讀展示的半形 `-` dash——InlineEdit 是可編輯欄位,空值 = placeholder 或空白
+- ❌ read 態語意標籤用 heading 時把它塞進 button——用隱形 Pressable 疊加,保留文件大綱