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

package/src/components/FileItem/file-item.stories.tsx

@@ -0,0 +1,289 @@
+// @story-history: hasInteractiveStates 由 anatomy.stories.tsx StateBehavior auto-compile owns(2026-05-15 F-migration);Default scenario 由 Rich / Compact / HoverSwap 等真實上傳情境 story 覆蓋,Disabled state 由 status="error" / "uploading" 真實 state 體現。
+import * as React from 'react'
+import type { Meta } from '@storybook/react'
+import { expect, fn, userEvent, within } from '@storybook/test'
+import { Trash2, ChevronDown } from 'lucide-react'
+import { FileItem } from './file-item'
+import { Button } from '@/design-system/components/Button/button'
+import { FileViewer, type FileInfo } from '@/design-system/components/FileViewer/file-viewer'
+// upload-manager 面板消費 overlay-surface header + body SSOT(非手刻)—— 跟 Popover/Dialog 同一組 primitive
+import { SurfaceHeader, SurfaceBody, COMPACT_HEADER_SLOT } from '@/design-system/patterns/overlay-surface/overlay-surface'
+import { PopoverTitle } from '@/design-system/components/Popover/popover'
+
+// 錯誤 description 範例(含 clickable "View log"):consumer 自由 ReactNode,通常用底線 link 表 clickable
+const errorDescWithLog = (
+  <>
+    There&rsquo;s something wrong.{' '}
+    <a href="#" className="underline hover:text-error-hover" onClick={(e) => e.preventDefault()}>
+      View log
+    </a>
+  </>
+)
+
+const meta: Meta<typeof FileItem> = {
+  title: 'Design System/Components/FileItem/展示',
+  tags: ['autodocs'],
+  component: FileItem,
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '以一致列項呈現檔名、類型、進度、狀態與檔案操作，可切換 compact 或 rich 內容。上傳佇列與附件清單需要逐檔回饋時使用。' } },
+  },
+}
+export default meta
+
+const noop = () => {}
+const keyboardOpen = fn()
+
+// FileItem row dedicated action(2026-04-23 統一 canonical):
+// **Row action 絕對值 cap = ≤ 24px,不隨 row tier 放大**。rich + compact 統一用
+// Button size="xs" iconOnly variant="text"(24 固定,≤ cap):
+// compact row 透過 FileItem 內部 suffix wrapper `[&>[data-unbounded]]:my-[calc((1lh-var(--field-height-xs))/2)]`
+// trick 讓 Button(24)layout footprint 收斂到 1lh(~18px)不撐高 row,觸控範圍仍 24。
+// Trash/Delete 非 dismiss 語意(dismiss 嚴格 = X close overlay),不套 `dismiss` prop——
+// Button variant="text" 本來就 fg-muted,視覺已弱化(兩 mode 同)。
+// 詳 item-anatomy.spec.md「Predicate」+「Row action 絕對值 cap」
+const deleteBtn = <Button size="xs" iconOnly variant="text" startIcon={Trash2} aria-label="刪除" onClick={noop} />
+const deleteBtnXs = deleteBtn
+
+export const Rich = {
+  name: '豐富樣式',
+  render: () => (
+    // rich(預設 form surface)各 status 展示:uploading / completed(保留 100% 完成條)/ error
+    // 也可傳 onClick/onDownload 讓整 row 點開(預設 FileViewer,consumer 決定)
+    // Rich 永遠 border card → list wrapper `gap-2` 防邊框相黏
+    <div className="flex flex-col gap-2 max-w-md">
+      <FileItem mode="rich" name="Alan Profile.png" status="uploading" progress={40}
+        description="5.7 MB of 7.5MB" thumbnailSrc="https://i.pravatar.cc/80?u=alan" actions={deleteBtn} />
+      <FileItem mode="rich" name="Alan Profile.png" status="completed"
+        description="5.7 MB" thumbnailSrc="https://i.pravatar.cc/80?u=alan"
+        onClick={keyboardOpen} onDownload={noop} actions={deleteBtn} />
+      <FileItem mode="rich" name="Alan Profile.png" status="error" progress={65}
+        description={errorDescWithLog} thumbnailSrc="https://i.pravatar.cc/80?u=alan"
+        onRetry={noop} actions={deleteBtn} />
+    </div>
+  ),
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    keyboardOpen.mockClear()
+    const action = await within(canvasElement).findByRole('button', { name: '開啟 Alan Profile.png' })
+    action.focus()
+    await userEvent.keyboard('{Enter}')
+    await expect(keyboardOpen).toHaveBeenCalledTimes(1)
+  },
+}
+
+export const Compact = {
+  name: '緊湊樣式',
+  render: () => (
+    // compact + status 各狀態展示(uploading / completed / error,永遠有 progress bar)
+    // list wrapper `gap-1`(4px)簡化 canonical — compact list 統一 gap-1,不論純/混合(2026-04-23)
+    <div className="flex flex-col gap-1 max-w-md">
+      <FileItem mode="compact" name="UXP T-Phone.csv" status="uploading" progress={60} actions={deleteBtnXs} />
+      <FileItem mode="compact" name="UXP T-Phone.csv" status="error" description={errorDescWithLog} actions={deleteBtnXs} />
+      <FileItem mode="compact" name="UXP T-Phone.csv" status="completed"
+        onClick={noop} onDownload={noop} actions={deleteBtnXs} />
+    </div>
+  ),
+}
+
+export const HoverSwap = {
+  name: '懸停替換',
+  render: () => (
+    <div className="flex flex-col max-w-md gap-4">
+      <div>
+        <div className="text-caption text-fg-muted mb-2">
+          ↓ 游標移入任一 row:completed 綠 ✓ 變 Download ↓,error 紅 ✗ 變 Retry ⟲
+        </div>
+        {/* Rich border card list:無外框 + `gap-2`(item-anatomy「連續 item 貼邊合法性」) */}
+        <div className="flex flex-col gap-2">
+          <FileItem mode="rich" name="Q1 營收報表.xlsx" status="completed" data-visual-hover-target
+            description="Uploaded to URL" thumbnailSrc="https://i.pravatar.cc/80?u=xls"
+            onDownload={noop} actions={deleteBtn} />
+          <FileItem mode="rich" name="合約草案 v3.pdf" status="error"
+            description="There's something wrong. View log"
+            thumbnailSrc="https://i.pravatar.cc/80?u=pdf"
+            onRetry={noop} actions={deleteBtn} />
+        </div>
+      </div>
+      <div>
+        <div className="text-caption text-fg-muted mb-2">
+          緊湊樣式也是同一套規則:狀態圖示與刪除鈕的大小、位置一致,垂直置中對齊
+        </div>
+        {/* Compact list 統一 gap-1(canonical 簡化) */}
+        <div className="flex flex-col gap-1">
+          <FileItem mode="compact" name="data-2024-q1.csv" status="completed"
+            onDownload={noop} actions={deleteBtnXs} />
+          <FileItem mode="compact" name="backup-failed.json" status="error"
+            description={<>Network timeout. <a href="#" className="underline hover:text-error-hover" onClick={(e) => e.preventDefault()}>View log</a></>}
+            onRetry={noop} actions={deleteBtnXs} />
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// ── FileViewer 真實整合 —— Clickable story 用 ──
+// onClick 打開 FileViewer,預設用 picsum 圖片模擬 preview(real-world consumer
+// 會用實際檔案 blob url / CDN url)。
+const attachmentFiles: FileInfo[] = [
+  {
+    id: 'attach-1',
+    url: 'https://picsum.photos/seed/report-pdf/1200/800',
+    name: '報告.pdf',
+    mimeType: 'application/pdf',
+    size: 2_400_000,
+    description: '2.3 MB',
+  },
+  {
+    id: 'attach-2',
+    url: 'https://picsum.photos/seed/contract-docx/1200/800',
+    name: '合約附件.docx',
+    mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    size: 1_100_000,
+    description: '1.1 MB',
+  },
+  {
+    id: 'attach-3',
+    url: 'https://picsum.photos/seed/data-csv/1200/800',
+    name: 'data.csv',
+    mimeType: 'text/csv',
+    size: 48_000,
+  },
+  {
+    id: 'attach-4',
+    url: 'https://picsum.photos/seed/backup-json/1200/800',
+    name: 'backup.json',
+    mimeType: 'application/json',
+    size: 320_000,
+  },
+]
+
+export const Clickable = {
+  name: '已上傳',
+  render: () => {
+    // Real FileViewer wiring:click → 打開 FileViewer at 對應 index
+    const [open, setOpen] = React.useState(false)
+    const [index, setIndex] = React.useState(0)
+    const openAt = (idx: number) => {
+      setIndex(idx)
+      setOpen(true)
+    }
+    return (
+      <>
+        {/* 2026-07-14 Dim 68 修:原本同一 list 依檔案類型混 rich(圖片)+ compact(文件),
+            違反 file-item.spec.md「❌ 不混用 rich + compact 在同一 list」(Invariant 1 —
+            高度差破壞 row rhythm)。改拆兩個區段:圖片整組 rich、文件整組 compact,
+            同區段 mode 統一(spec 建議的分區段做法);FileViewer index 跨兩區段連續。 */}
+        <div className="flex flex-col gap-4 max-w-md">
+          <div className="flex flex-col gap-1.5">
+            <h3 className="text-caption font-medium text-fg-muted">圖片</h3>
+            <div className="flex flex-col gap-2">
+              {attachmentFiles.slice(0, 2).map((f, i) => (
+                <FileItem
+                  key={f.id}
+                  mode="rich"
+                  name={f.name}
+                  description={f.description ?? (f.size != null ? `${(f.size / 1024 / 1024).toFixed(1)} MB` : '—')}
+                  thumbnailSrc={f.url}
+                  onClick={() => openAt(i)}
+                  actions={deleteBtn}
+                />
+              ))}
+            </div>
+          </div>
+          <div className="flex flex-col gap-1.5">
+            <h3 className="text-caption font-medium text-fg-muted">文件</h3>
+            <div className="flex flex-col gap-1">
+              {attachmentFiles.slice(2).map((f, i) => (
+                <FileItem
+                  key={f.id}
+                  mode="compact"
+                  name={f.name}
+                  onClick={() => openAt(i + 2)}
+                  actions={deleteBtn}
+                />
+              ))}
+            </div>
+          </div>
+        </div>
+        <FileViewer files={attachmentFiles} open={open} onOpenChange={setOpen} index={index} onIndexChange={setIndex} />
+      </>
+    )
+  },
+}
+
+export const CompactMixed = {
+  name: '緊湊 混合',
+  render: () => (
+    // Real-world:email 草稿 — 新上傳中(status=uploading/error)+ 舊已存附件(無 status 靜態)混在同 list
+    // 重要 invariant:upload-manager 的 completed(bar 100% + ✓)跟靜態(無 bar)不共存
+    // —— completed-保留 是「剛完成的 upload session」,無 status 是「已存 attachment」,
+    //    業務語義互斥(表單情境完成後 consumer 會清掉 status 轉靜態)。
+    // 這 mixed 情境只含:上傳中(uploading/error)+ 已存附件(saved attachments,無 status)
+    <div className="flex flex-col gap-1 max-w-md">
+      <FileItem mode="compact" name="圖片草稿.png" status="uploading" progress={40} actions={deleteBtnXs} />
+      <FileItem mode="compact" name="回覆範本.docx" onClick={noop} actions={deleteBtnXs} />
+      <FileItem mode="compact" name="backup-failed.json" status="error"
+        description={<>Network timeout. <a href="#" className="underline hover:text-error-hover" onClick={(e) => e.preventDefault()}>View log</a></>}
+        onRetry={noop} actions={deleteBtnXs} />
+      <FileItem mode="compact" name="附件封面.pdf" onClick={noop} actions={deleteBtnXs} />
+    </div>
+  ),
+}
+
+// surface="upload-manager":Google Drive / Dropbox 上傳管理面板。面板組合 canonical(2026-06-03 圖五/圖一 user 校準):
+//   - 左右一律 loose(16px,對齊 header);上下目標「邊緣→item ink」= tight(12px),通則 container 該側 = 12 − item 該側留白
+//   - rich item 上下留白 0 → py-tight(12/12 對稱);compact 上留 8(item py)→ pt-1(4),下進度條貼底留 0 → pb-tight(12)
+//   - 列間 gap 反映密度:rich = tight(12px,卡片+48 縮圖)/ compact = 4px(密集文字列)
+//   - rich item 拿掉全部 padding(px-0 py-0,列高靠 avatar 48);左右交給面板,避免雙重 L/R。對比 surface=form 的 border card。
+export const UploadManagerSurface = {
+  name: '上傳管理器 · 豐富(無邊框)',
+  render: () => (
+    <div className="max-w-md flex flex-col rounded-lg border border-border bg-surface-raised shadow-[var(--elevation-200)]">
+      {/* header 消費 overlay-surface SurfaceHeader + PopoverTitle(輕量浮層 chrome SSOT,非手刻):
+          px-loose py-tight + border-b + chevron(variant=text → 自動 data-unbounded → 套 slot 負 my trick)*/}
+      <SurfaceHeader className={`justify-between ${COMPACT_HEADER_SLOT}`}>
+        <div className="flex-1 min-w-0"><PopoverTitle>正在上傳 3 個項目</PopoverTitle></div>
+        <Button iconOnly variant="text" size="sm" startIcon={ChevronDown} aria-label="收合" onClick={noop} />
+      </SurfaceHeader>
+      {/* body 消費 overlay-surface SurfaceBody(非手刻;含 px-loose py-tight + flex-1 scroll 鏈)。
+          rich:py-tight(SurfaceBody 預設)+ gap-tight = 垂直對稱 12px */}
+      <SurfaceBody className="flex flex-col gap-[var(--layout-space-tight)]">
+        <FileItem mode="rich" surface="upload-manager" name="Alan Profile.png" status="uploading" progress={40}
+          description="5.7 MB of 7.5 MB" thumbnailSrc="https://i.pravatar.cc/80?u=alan" actions={deleteBtn} />
+        <FileItem mode="rich" surface="upload-manager" name="Q1 營收報表.xlsx" status="completed"
+          description="2.4 MB" thumbnailSrc="https://i.pravatar.cc/80?u=xls" onDownload={noop} actions={deleteBtn} />
+        <FileItem mode="rich" surface="upload-manager" name="合約草案 v3.pdf" status="error"
+          description={errorDescWithLog} thumbnailSrc="https://i.pravatar.cc/80?u=pdf" onRetry={noop} actions={deleteBtn} />
+      </SurfaceBody>
+    </div>
+  ),
+}
+
+// surface="upload-manager" 的 compact list:左右 loose 16(同 rich,對齊 header);上下「不對稱」=「12 − item 該側留白」:
+// top !pt-1=4(item 自帶 py-2 的 8 + 4 = 12),bottom 12(進度條貼底、item 下方無留白);gap 只 4px(密集列)。
+// 對比 rich panel(item py-0 → 上下對稱 12 / gap 12),demo 兩 mode 密度差異。
+export const UploadManagerCompactSurface = {
+  name: '上傳管理器 · 緊湊(無邊框)',
+  render: () => (
+    <div className="max-w-md flex flex-col rounded-lg border border-border bg-surface-raised shadow-[var(--elevation-200)]">
+      {/* header 消費同一個 overlay-surface SurfaceHeader + PopoverTitle SSOT(同 rich panel)*/}
+      <SurfaceHeader className={`justify-between ${COMPACT_HEADER_SLOT}`}>
+        <div className="flex-1 min-w-0"><PopoverTitle>同步 3 個檔案</PopoverTitle></div>
+        <Button iconOnly variant="text" size="sm" startIcon={ChevronDown} aria-label="收合" onClick={noop} />
+      </SurfaceHeader>
+      {/* body 消費 SurfaceBody(px-loose + pb-tight 自 SSOT);compact 只 override top:`!pt-1`(4px,
+          item 文字上方自帶 8px → 4+8=12;bottom 留 SurfaceBody 預設 py-tight=12,因進度條貼底無留白)。
+          用 `!`(important)而非 `pt-1`:twMerge 不 strip 基底 py-[tight] → 非 important 時 top 12/4 競爭看
+          stylesheet 生成順序(非決定性);`!` 強制 top=4 決定性勝(對齊 List-as-region `!px-0` override 慣例)。
+          列間 gap-1(4px,密集列)。 */}
+      <SurfaceBody className="flex flex-col gap-1 !pt-1">
+        <FileItem mode="compact" surface="upload-manager" name="季度報告.docx" status="uploading" progress={60}
+          onClick={noop} actions={deleteBtn} />
+        <FileItem mode="compact" surface="upload-manager" name="客戶名單.csv" status="completed"
+          onClick={noop} actions={deleteBtn} />
+        <FileItem mode="compact" surface="upload-manager" name="封面.png" status="error"
+          description={errorDescWithLog} onRetry={noop} actions={deleteBtn} />
+      </SurfaceBody>
+    </div>
+  ),
+}

package/src/components/FileItem/file-item.tsx

@@ -5,17 +5,17 @@ import { cn } from '@/lib/utils'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
 import { Button } from '@/design-system/components/Button/button'
 import { ProgressBar } from '@/design-system/components/ProgressBar/progress-bar'
-import { ItemContent, ItemPrefix } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
 /**
  * FileItem — 檔案顯示 / 上傳進度
  *
- * Typography: 閱讀模式 — text-body (14px) 預設行高 (1.5)
+ * Typography: 兩 mode 統一 scanning — text-body (14px) + leading-compact (1.3)(詳 spec「Typography」段,2026-04-23)
  *
  * 兩種 mode（精簡 vs 完整內容呈現）:
  *
  * compact（★ default）: Paperclip 16px 在左。右側 content + bar。
- *   py = gap = 4px (gap-1)，對稱。
+ *   padding 詳 spec「Padding」表(form: px-3 py-2;surface=upload-manager: px-0 保留 py-2)。
  *   description 只有 error 才顯示。
  *   bar 跟文字左邊對齊（在 icon 右邊的 column 內）。
  *
@@ -25,7 +25,7 @@ import { ItemContent, ItemPrefix } from '@/design-system/patterns/element-anatom
  *   無 bar → justify-center（文字垂直置中對齊 avatar）
  *
  * status 可選。不傳 = 已上傳檔案（無 bar，可點擊下載）。
- * onClick → hover:bg-neutral-hover + cursor-pointer。
+ * onClick → 只加 cursor-pointer(**永不顯示 hover-bg**;FileItem 三型態皆 permanent-anchored,詳 spec「Hover 行為 canonical」)。
  */
 
 const STATUS_ICON = {
@@ -52,6 +52,16 @@ export interface FileItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
    * - `rich`：縮圖 + 檔名 + size + status + progress 的完整 card 呈現
    */
   mode?: 'compact' | 'rich'
+  /**
+   * 清單所在的 surface context（2026-06-03 codify rich-borderless）：
+   * - `form`（預設）：rich = border card（自立輪廓，Slack/Notion/Linear attachment 慣例）
+   * - `upload-manager`：rich = **無邊框**（Google Drive/Dropbox 上傳管理面板 —— 面板自身已是容器，
+   *   card border 多餘 = 雙層容器）；avatar 作每筆 item 視覺邊界。compact 的進度條/灰底不受 surface 影響
+   *   （由 status 決定）。
+   * surface-driven（非 status-driven）：避免 form 內 rich 上傳中變無邊框、存好變 card 的邊框閃爍。
+   * 列間 gap 由 List wrapper canonical 決定（form rich 8px / upload-manager rich 12px tight / compact 4px，見 spec）。
+   */
+  surface?: 'form' | 'upload-manager'
   status?: 'uploading' | 'completed' | 'error'
   progress?: number
   /** rich mode: 檔案大小、狀態訊息。compact: 只有 error 才顯示。 ReactNode 支援 inline clickable link(如「View log」)。 */
@@ -59,6 +69,8 @@ export interface FileItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   thumbnailSrc?: string
   actions?: React.ReactNode
   onClick?: () => void
+  /** 整列 primary action 的 accessible name；預設 `開啟 {name}`。 */
+  actionAriaLabel?: string
   /**
    * Hover 動作(passive 狀態 icon 變互動 button 的 UX):
    * - `onDownload`:有值時,`status="completed"` 的綠 ✓ icon 在 row hover 時
@@ -79,12 +91,14 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     {
       name,
       mode = 'compact',
+      surface = 'form',
       status,
       progress = 0,
       description,
       thumbnailSrc,
       actions,
       onClick,
+      actionAriaLabel = `開啟 ${name}`,
       onDownload,
       onRetry,
       className,
@@ -101,30 +115,30 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     const showDesc = isRich ? !!description : (status === 'error' && !!description)
 
     // Hover 行為 canonical(2026-04-23 user 校準):**FileItem 永不顯示 hover-bg**。
-    // 三種型態都有永久 visual anchor:rich = border card / compact Type B = bg-secondary /
-    // compact Type A = 底部 progress bar(分隔線型 affordance)——再加 hover-bg 是
+    // 各型態都有永久 visual anchor:rich surface=form = border card / rich surface=upload-manager
+    // = avatar 48 thumbnail 作 item 邊界(無邊框)/ compact 無 status = bg-secondary /
+    // compact 有 status = 底部 progress bar(分隔線型 affordance)——再加 hover-bg 是
     // double-emphasis,視覺雜。世界級共識(Slack / Notion / Figma / Gmail 皆無 hover-bg):
     // permanent-anchored 元件 hover 只靠 cursor + action icon fade / border highlight,
     // 不靠 row bg。onClick 存在時只給 `cursor-pointer`,affordance 靠 cursor + 點擊行為本身。
     const hoverClass = onClick ? 'cursor-pointer' : ''
 
     // 消費 ProgressBar 元件(SSOT);不再自 roll bar。
-    // height override:compact mode 用 2px(極密集 row layout),rich mode 用預設 4px。
-    // 這是 ProgressBar `height` prop 的唯一合法 consumer(見 progress-bar.tsx docblock)。
+    // compact mode 用 2px(極密集 row layout),rich mode 用預設 4px。這是 FileItem
+    // 私有 composition 細節；ProgressBar 公開 API 維持單一 4px、沒有 height/size 軸。
     // a11y(2026-04-25 axe aria-progressbar-name):aria-label 用 file name 作 context。
     const progressBar = hasStatus ? (
       <ProgressBar
         value={progressWidth}
         status={PROGRESS_STATUS_MAP[status!]}
-        height={isRich ? undefined : 2}
+        className={isRich ? undefined : '!h-0.5'}
         aria-label={`${name} 上傳進度`}
       />
     ) : null
 
     // suffix 對齊 label 第一行(item-anatomy「24px 閾值對齊規則」小 suffix canonical):
-    // icons 16 ≤ 24 屬小 suffix,統一 `h-[1lh]` inline,不因 desc wrap 改公式。
-    // 兩 mode 同公式,跟 item-anatomy 一致。
-    const suffixAlign = 'h-[1lh]'
+    // icons 16 ≤ 24 屬小 suffix,統一 h-[1lh] inline(由 ItemSuffix primitive 提供),
+    // 不因 desc wrap 改公式。兩 mode 同公式,跟 item-anatomy 一致。
 
     // Status slot 幾何(2026-04-23 user 統一):rich + compact 都用 `var(--field-height-xs)`(24)
     // 容器,裡面 Button xs iconOnly variant="text"(auto data-unbounded)。
@@ -133,8 +147,8 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     const slotHw = 'var(--field-height-xs)'
 
     const hoverAction =
-      status === 'completed' && onDownload ? { icon: Download, onClick: onDownload, label: '下載' } :
-      status === 'error' && onRetry        ? { icon: RotateCw, onClick: onRetry,    label: '重試' } :
+      status === 'completed' && onDownload ? { icon: Download, onClick: onDownload, label: `下載 ${name}` } :
+      status === 'error' && onRetry        ? { icon: RotateCw, onClick: onRetry,    label: `重試 ${name}` } :
       null
 
     const statusSlot = statusConfig ? (
@@ -147,9 +161,10 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
         <statusConfig.icon
           size={ICON_PX}
           className={cn(
-            'shrink-0 transition-opacity',
+            'shrink-0 transition-opacity motion-reduce:duration-0',
             statusConfig.color,
-            hoverAction && 'group-hover/row:opacity-0',
+            // 2026-07-05 D4:鍵盤 focus 同步觸發 swap(:has(:focus-visible),對齊 item-anatomy SUFFIX_HOVER_REVEAL_BY_GROUP SSOT)
+            hoverAction && 'group-hover/row:opacity-0 group-has-[:focus-visible]/row:opacity-0',
           )}
           aria-hidden
         />
@@ -162,17 +177,20 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
             startIcon={hoverAction.icon}
             aria-label={hoverAction.label}
             onClick={(e) => { e.stopPropagation(); hoverAction.onClick() }}
-            className="absolute inset-0 opacity-0 group-hover/row:opacity-100 transition-opacity"
+            className="absolute inset-0 opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity motion-reduce:duration-0"
           />
         )}
       </span>
     ) : null
 
+    // 2026-07-16 dim 39/DA3:消費 ItemSuffix primitive(照 Notice 2026-06-15 已遷模式)。
+    // ItemSuffix base geometry(h-[1lh] shrink-0 ml-auto flex items-center gap-2)= 原手刻
+    // div 的 flex items-center gap-2 shrink-0 h-[1lh];多出的 ml-auto 為 no-op(左鄰
+    // ItemContent 是 flex-1,已把 suffix 推到右緣)→ 像素相等。hoverReveal 預設 false,
+    // 不干擾本檔自有的 statusSlot hover-swap 機制(group-hover/row 系)。
     const suffix = (
-      <div
+      <ItemSuffix
         className={cn(
-          'flex items-center gap-2 shrink-0',
-          suffixAlign,
           // data-unbounded chrome-canonical trick:let Button xs (24) live inside h-[1lh]
           // wrapper(compact ~18.2 / rich ~18.2 scanning)without pushing row height。
           // 視覺/hit area 仍 24,layout footprint 收斂到 1lh。同 overlay-surface
@@ -188,7 +206,7 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
         )}
         {statusSlot}
         {actions}
-      </div>
+      </ItemSuffix>
     )
 
     // content row — 消費 ItemContent primitive(封裝 label + desc + mt-gap token SSOT)。
@@ -207,13 +225,9 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
       </div>
     )
 
-    // a11y(2026-04-25 nested-interactive fix):FileItem row 含 inner interactive
-    // (hover-swap action button / ProgressBar / Avatar hoverCard trigger)。原本
-    // role='button' + tabIndex=0 整列可鍵盤點,與 inner buttons 構成 nested-interactive
-    // (axe serious)。移除 row 層 button semantic → mouse 仍可點(onClick 保留),
-    // 鍵盤 user 直接 tab 到 inner primary action。Trade-off:失去「整列 Enter 開啟」
-    // 但滿足 WCAG;世界級對照:Slack message row / Notion page row 同模式 — row 只
-    // mouse 點,inner 有 explicit 按鈕負責鍵盤。
+    // a11y nested-interactive contract:row 含 hover-swap / trailing action buttons，故 row
+    // 本身不可設 role=button + tabIndex。Primary keyboard path 由下方 sibling native button
+    // 承接；mouse 仍由 row onClick 承接，兩者皆呼叫同一 callback。
     const rowA11y = {}
 
     // Compact 靜態背景(AR20):無進度條 → 顯示 `bg-secondary`(= neutral-3)作「檔案已上傳 /
@@ -224,17 +238,37 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     // 是 semantic token 橋接的 utility(見 `tokens/color/semantic.css`@theme inline),
     // 底色同樣指向 `--color-neutral-3`。對齊 Badge low / ProgressBar track SSOT。
     const compactStaticBg = !progressBar ? 'bg-secondary' : ''
+    // Primary row action 與 trailing actions 是 sibling controls，不把整列設成 role=button，
+    // 因此不會形成 nested-interactive。透明 full-row button 只接 keyboard/focus；pointer
+    // 仍由既有 row onClick 接手，保持 hit area 與 consumer callback contract 不變。
+    const keyboardPrimaryAction = onClick ? (
+      <button
+        type="button"
+        aria-label={actionAriaLabel}
+        className="absolute inset-0 opacity-0 pointer-events-none"
+        onClick={(event) => {
+          event.stopPropagation()
+          onClick()
+        }}
+      />
+    ) : null
 
-    // ── rich(含縮圖完整呈現)——AR17 canonical:加邊框 + gap-2 ──
-    // Rich mode 是「檔案 card」風格,外框讓每個 row 視覺上是獨立 card
-    // (Slack / Notion / Linear attachment 慣例)
+    // ── rich(含縮圖完整呈現)——AR17 canonical:surface=form 加邊框 card / surface=upload-manager 無邊框 ──
+    // Rich surface=form 是「檔案 card」風格,外框讓每個 row 視覺上是獨立 card(Slack / Notion /
+    // Linear attachment 慣例);surface=upload-manager 無邊框,avatar 作 item 邊界(面板自身是容器,
+    // 見 file-item.spec.md「邊框 / 背景」表)
     if (isRich) {
       return (
         <div
           ref={ref}
           className={cn(
-            'group/row flex items-start gap-2 px-3 py-3 w-full text-body leading-compact transition-colors',
-            'border border-divider rounded-md bg-surface',
+            'group/row relative flex items-start gap-2 w-full text-body leading-compact transition-colors',
+            'has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring',
+            // surface=form → border card(自立輪廓);surface=upload-manager → 無邊框(box 自身是容器,
+            // avatar 作 item 邊界)。2026-06-03 codify rich-borderless(原僅 spec 旁註,consumer 自己移除)。
+            // 2026-06-03 圖五:upload-manager rich 拿掉 px+py(卡片移除後 py 多餘,列高靠 avatar 48 的 content minHeight;
+            // 容器 + gap 控制間距)。form 保留 px-3 py-3 卡片內距。
+            surface === 'upload-manager' ? 'rounded-md' : 'px-3 py-3 border border-divider rounded-md bg-surface',
             hoverClass,
             className,
           )}
@@ -242,6 +276,7 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
           {...rowA11y}
           {...props}
         >
+          {keyboardPrimaryAction}
           <Avatar src={thumbnailSrc} alt={name} size={AVATAR_SIZE} shape="square" className="shrink-0" />
           {/* Rich layout invariant(2026-04-23 user 校準):
               - content col minHeight = AVATAR_SIZE(48),確保 1-line desc 時內容 ≥ avatar 高
@@ -264,20 +299,27 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
       )
     }
 
-    // ── compact: py-2 對稱, bar absolute 底部 ──
+    // ── compact: py-2, bar absolute 底部 ──
+    // 左右 padding 單一來源(SSOT):form=12px(= px-3);upload-manager=0(由面板提供 L/R)。
+    // progress bar 是 absolute 定位,其 left/right 必須跟此值「同源」—— 否則 surface 一拿掉 padding,
+    // bar 的 offset 沒同步就會對齊跑掉(2026-06-03 圖五 bug:原本 left/right 寫死 0.75rem 假設 px-3)。
+    const compactPadX = surface === 'upload-manager' ? 0 : 12
     return (
       <div
         ref={ref}
         className={cn(
-          'group/row relative flex items-start gap-2 px-3 py-2 w-full text-body leading-compact transition-colors rounded-md',
+          'group/row relative flex items-start gap-2 py-2 w-full text-body leading-compact transition-colors rounded-md',
           compactStaticBg,
+          'has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring',
           hoverClass,
           className,
         )}
+        style={{ paddingInline: compactPadX }}
         onClick={onClick}
         {...rowA11y}
         {...props}
       >
+        {keyboardPrimaryAction}
         <ItemPrefix>
           <Paperclip size={ICON_PX} className="shrink-0 text-fg-muted" aria-hidden />
         </ItemPrefix>
@@ -288,9 +330,13 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
           {contentRow}
         </div>
 
-        {/* ProgressBar: absolute 底部, left 對齊 label(跳過 icon + gap) */}
+        {/* ProgressBar: absolute 底部。left/right 與 compactPadX 同源:
+            left = padX + icon + gap-2(0.5rem)對齊 label 首字;right = padX 收在 row 內緣。 */}
         {progressBar && (
-          <div className="absolute bottom-0 right-3" style={{ left: `calc(0.75rem + ${ICON_PX}px + 0.5rem)` }}>
+          <div
+            className="absolute bottom-0"
+            style={{ left: `calc(${compactPadX}px + ${ICON_PX}px + 0.5rem)`, right: compactPadX }}
+          >
             {progressBar}
           </div>
         )}
@@ -311,9 +357,9 @@ export const fileItemMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-secondary', 'bg-surface'],
+    bg: ['bg-secondary', 'bg-surface'],
     fg: ['text-fg-muted', 'text-fg-secondary'],
     ring: [],
   },

package/src/components/FileItem/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 './file-item'