@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

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

@@ -6,6 +6,7 @@ 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, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { STACK_GAP_PX } from '@/design-system/tokens/uiSize/stack-gap'
 
 /**
  * FileItem — 檔案顯示 / 上傳進度
@@ -15,7 +16,8 @@ import { ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/el
  * 兩種 mode（精簡 vs 完整內容呈現）:
  *
  * compact（★ default）: Paperclip 16px 在左。右側 content + bar。
- *   padding 詳 spec「Padding」表(form: px-3 py-2;surface=upload-manager: px-0 保留 py-2)。
+ *   padding 詳 spec「Padding」表(form: px-3 py-2;surface=upload-manager: 列自帶左右 loose、上下 tight/2,
+ *   面板 body 左右 0 —— 2026-09-25 待辦總帳 B12,可點的列滑過底色鋪到面板邊)。
  *   description 只有 error 才顯示。
  *   bar 跟文字左邊對齊（在 icon 右邊的 column 內）。
  *
@@ -25,7 +27,7 @@ import { ItemContent, ItemPrefix, ItemSuffix } from '@/design-system/patterns/el
  *   無 bar → justify-center（文字垂直置中對齊 avatar）
  *
  * status 可選。不傳 = 已上傳檔案（無 bar，可點擊下載）。
- * onClick → 只加 cursor-pointer(**永不顯示 hover-bg**;FileItem 三型態皆 permanent-anchored,詳 spec「Hover 行為 canonical」)。
+ * onClick → cursor-pointer + 滑過底色(只有點了會有反應的才加,依平常底色配對;詳 spec「滑過」段,待辦總帳 B12)。
  */
 
 const STATUS_ICON = {
@@ -59,7 +61,8 @@ export interface FileItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
    *   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）。
+   * 列間 gap 由 List wrapper canonical 決定(form rich 8px / form compact 4px / upload-manager 0 —— 列自帶上下 tight/2,
+   * 列間 ink 距仍 12,2026-09-25 待辦總帳 B12;見 spec)。
    */
   surface?: 'form' | 'upload-manager'
   status?: 'uploading' | 'completed' | 'error'
@@ -85,6 +88,62 @@ export interface FileItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   onRetry?: () => void
 }
 
+// ── compact 進度條的左右位置(單一來源)──
+// 進度條本身(下方 compact 分支)與焦點框的挖空(fileItemRingCutoutStyle)都從這裡取,內距一改兩者一起動
+// (2026-06-03 圖五 bug:bar 的 left / right 寫死、內距一改就對不齊)。
+//   form:左右 12px(= px-3)。upload-manager(2026-09-25 待辦總帳 B12):左右 loose(= 原本面板給的值,文字 x 不變)。
+//   left = 內距 + icon + gap-2(0.5rem)→ 對齊 label 首字;right = 內距 → 收在列內緣。
+function compactBarInset(surface: FileItemProps['surface']) {
+  const padX = surface === 'upload-manager' ? 'var(--layout-space-loose)' : '12px'
+  return { padX, left: `calc(${padX} + ${ICON_PX}px + 0.5rem)`, right: padX }
+}
+
+/**
+ * 焦點框在進度條兩端留的縫(px)= DS 通用的「疊在一起的兩樣東西」之間的縫(`tokens/uiSize/stack-gap.ts`,
+ * 全域外描邊的 outline-offset、頭像堆疊的縫、步驟條外圈的縫都是同一個 token)。
+ */
+const BAR_RING_GAP_PX = STACK_GAP_PX
+
+/**
+ * @internal
+ * 焦點框的「框圖層」:與列同形同大的 `::before`(file-item.spec.md「焦點框 × 貼著列底的進度條」)。
+ * 只在**列底貼著進度條**時用 —— form 的 compact 列有 status 時。upload-manager 的進度條離列底 tight/2、
+ * rich 的進度條在內容區,都碰不到框,照舊把框畫在列上。
+ * 為什麼要另一層:進度條住在列裡。框若畫在列上,列是進度條的祖先,遮罩會連進度條一起挖掉;
+ * 畫在 `::before` 上,遮罩只挖框。層疊不變:`::before` 是第一個定位子層,進度條(absolute)仍畫在它上面;
+ * 而且洞裡根本沒有框,進度條與框誰畫在上面都不影響結果(CSS UI 4 把 outline 的疊放順序留給瀏覽器自己決定,
+ * 「The stacking of the rendering of these outlines is explicitly left up to implementations」)。
+ * 這裡只有位置與遮罩,**不含觸發條件**:FileItem 自己的列由整列隱形鈕觸發、FileUpload 的清單列由列自己的
+ * `:focus-visible` 觸發,各自在使用端寫。線寬、顏色、往內 2px、圓角全部照舊來自 `focus-ring-inset`
+ * (`ds-canonical/references/focus-canonical.md`「框怎麼畫」),不是第四種幾何。
+ */
+export const FILE_ITEM_RING_LAYER_CLASS =
+  'before:absolute before:inset-0 before:rounded-[inherit] before:pointer-events-none before:[mask:var(--file-item-ring-cutout)]'
+
+/**
+ * @internal
+ * 框圖層的遮罩(`--file-item-ring-cutout`)。列底沒有貼著進度條時回 `undefined` —— 呼叫端據此照舊把框畫在列上。
+ * 遮罩 = 三塊保留區的聯集:上半部整條 + 左段 + 右段。挖掉的是「進度條那一段(兩端各多 BAR_RING_GAP_PX)的下半部」,
+ * 框在那個範圍裡只有底邊,所以挖掉的只有底邊那一段。露出來的是**真正在後面的東西**(列自己的滑過色、卡片、面板、頁面),
+ * 不需要知道底色是什麼(與 `avatar.tsx` 頭像堆疊「挖空,不是外圈」同一個理由:深色的 `--surface` 本身半透明,
+ * 墊任何固定底色都會在某種容器上錯色)。
+ */
+export function fileItemRingCutoutStyle({
+  mode = 'compact',
+  surface = 'form',
+  status,
+}: Pick<FileItemProps, 'mode' | 'surface' | 'status'>): React.CSSProperties | undefined {
+  if (mode !== 'compact' || surface === 'upload-manager' || !status) return undefined
+  const { left, right } = compactBarInset(surface)
+  const keep = 'linear-gradient(#000 0 0)' // 遮罩只看不透明度;顏色無意義
+  return {
+    ['--file-item-ring-cutout' as string]:
+      `${keep} top / 100% 50% no-repeat, ` +
+      `${keep} left / calc(${left} - ${BAR_RING_GAP_PX}px) 100% no-repeat, ` +
+      `${keep} right / calc(${right} - ${BAR_RING_GAP_PX}px) 100% no-repeat`,
+  }
+}
+
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
   (
@@ -114,14 +173,18 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     // compact 只有 error 才顯示 description
     const showDesc = isRich ? !!description : (status === 'error' && !!description)
 
-    // Hover 行為 canonical(2026-04-23 user 校準):**FileItem 永不顯示 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' : ''
+    // 滑過底色(2026-09-25 待辦總帳 B12;取代 2026-04-23「FileItem 永不顯示 hover-bg」)。
+    // user 原話:「要點了會有反應的才加，並確保加上去之後不會有任何視覺奇怪的地方，且按鈕的互動樣式也是自然疊加上去吧？用再亮一層這樣的措辭是否不夠精準？」
+    // → 只有傳了 onClick 的列 / 卡才有滑過底色;沒傳就沒有(✓→下載鈕的換位照舊,那顆鈕有自己的滑過色)。
+    // 換上什麼色依「平常底色」配對(tokens/color/color.spec.md「Hover 換色配對總則」),直接寫在下方各 mode 的 cn() 裡、
+    // 跟靜止底同一次呼叫 —— scripts/hover-own-pair-invariant.mjs 才看得到這一對:
+    //   rich + form 卡片 bg-surface(「底」)→ 底不換,疊一層 bg-interaction-hover
+    //   compact 小膠囊 bg-secondary → 換成自己的下一階 bg-secondary-hover
+    //   透明的列(compact 有進度條、upload-manager 的列)→ 換成 bg-neutral-hover
+    // 不加按住(active:)那一階:FileItem「列按下深一階」是待辦總帳 N4 / F 模型 D3(2),尚未提問(AI 推導:不先替 user 決定)。
+    // 列內按鈕(刪除、✓→下載)滑過時換上自己的 neutral-hover(半透明),自然疊在列的滑過色上,不寫特例
+    // (color.spec.md「巢狀滑過」段)。
+    const isUploadManager = surface === 'upload-manager'
 
     // 消費 ProgressBar 元件(SSOT);不再自 roll bar。
     // compact mode 用 2px(極密集 row layout),rich mode 用預設 4px。這是 FileItem
@@ -143,7 +206,8 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     // Status slot 幾何(2026-04-23 user 統一):rich + compact 都用 `var(--field-height-xs)`(24)
     // 容器,裡面 Button xs iconOnly variant="text"(auto data-unbounded)。
     // Compact 不影響 row 高度 = suffix wrapper 的 data-unbounded CSS 讓 Button layout
-    // 收斂到 1lh(同 compact row 內容高),視覺/touch target 仍 24。
+    // 收斂到 1lh(同 compact row 內容高),視覺與命中區仍 24(命中 ≡ 可視,見
+    // ds-canonical/references/hit-area-canonical.md;2026-09-24 把原文的「touch target」正名為命中區)。
     const slotHw = 'var(--field-height-xs)'
 
     const hoverAction =
@@ -157,18 +221,19 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
         className="relative inline-flex items-center justify-center shrink-0"
         style={{ width: slotHw, height: slotHw }}
       >
-        {/* Passive 狀態 icon:預設可見;若有 hover-swap,row-hover 時淡出 */}
+        {/* Passive 狀態 icon:預設可見;若有 hover-swap,row-hover 時瞬間隱藏、換上操作鈕(不淡出;
+            tokens/motion/motion.spec.md「hover 回饋不做過渡」,2026-09-26 延伸到滑過才出現的按鈕,待辦總帳 L9 / N4(3)) */}
         <statusConfig.icon
           size={ICON_PX}
           className={cn(
-            'shrink-0 transition-opacity motion-reduce:duration-0',
+            'shrink-0',
             statusConfig.color,
             // 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
         />
-        {/* Active action:row-hover 時淡入(rich + compact 同 Button xs 統一) */}
+        {/* Active action:row-hover 時瞬間出現(不淡入,同上;rich + compact 同 Button xs 統一) */}
         {hoverAction && (
           <Button
             variant="text"
@@ -177,7 +242,7 @@ 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 group-has-[:focus-visible]/row:opacity-100 transition-opacity motion-reduce:duration-0"
+            className="absolute inset-0 opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100"
           />
         )}
       </span>
@@ -205,7 +270,30 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
           <span className="text-fg-secondary tabular-nums">{progress}%</span>
         )}
         {statusSlot}
-        {actions}
+        {/* **動作鈕不搶整列 click,由元件自己吃掉,不要求 consumer 每次記得**(2026-09-24)。
+            Canonical 早就寫了:`patterns/element-anatomy/item-anatomy.spec.md`「suffix 可以塞什麼」表的 Inline Action 列
+            「明確點擊靶子 ≤ 24px,`stopPropagation` 避免搶 row click」。
+            但先前只有 FileItem **自家**的 hover-swap 鈕做到(本檔 statusSlot 裡 `hoverAction` 那顆 Button 的 `stopPropagation`),consumer 從 `actions`
+            傳進來的鈕沒有任何人做 —— 於是「點刪除 → 整列 onClick 也跟著跑 → 檔案被開起來」
+            在我們自己的示範裡活到今天(實測:`已上傳` 這則點刪除鈕,FileViewer 就開)。
+            同一列同時有整列 onClick 和 trailing action 時,這是**必然**會犯的錯,所以答案不是
+            在文件裡要 consumer 記得,而是元件內部把邊界劃好(同 `agent-panel.tsx` 選項卡裡「其他(自由輸入)」輸入框的
+            `stopPropagation` / `data-table.tsx` 選取欄 `cellEl` 裡 Checkbox 與 RadioGroupItem 的 `stopPropagation`)。
+            **只包 `actions`、不包整個 suffix**:suffix 裡的 `{progress}%` 與被動狀態圖示是唯讀
+            metadata,item-anatomy「suffix 可以塞什麼」表明寫唯讀 metadata「不搶 row click target」
+            = 點它仍該開整列,所以那兩個不進這層。
+            `data-unbounded` 掛在**這一層**:上面那條 `[&>[data-unbounded]]` 只認 ItemSuffix 的
+            **直接**子元素;包一層之後負 margin 的承接者換成本層,否則 24 高的鈕會把 compact 列撐高。
+            實測 compact / rich / upload-manager 三則的列高、suffix 高、鈕的座標與尺寸改前改後逐項相同。 */}
+        {actions && (
+          <span
+            data-unbounded="true"
+            className="inline-flex items-center gap-2"
+            onClick={(e) => e.stopPropagation()}
+          >
+            {actions}
+          </span>
+        )}
       </ItemSuffix>
     )
 
@@ -230,14 +318,13 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
     // 承接；mouse 仍由 row onClick 承接，兩者皆呼叫同一 callback。
     const rowA11y = {}
 
-    // Compact 靜態背景(AR20):無進度條 → 顯示 `bg-secondary`(= neutral-3)作「檔案已上傳 /
-    // 靜態列表」視覺區隔,跟「上傳中(有 progress bar)」對照。hover 不改 bg(見上方
-    // hoverClass canonical:FileItem 永不顯示 hover-bg)。
-    // **為什麼 bg-secondary 不 bg-neutral-3**:`bg-neutral-3` 不是合法 Tailwind utility
-    // (primitive token `--color-neutral-3` 沒經 `@theme inline` 橋接);`bg-secondary`
-    // 是 semantic token 橋接的 utility(見 `tokens/color/semantic.css`@theme inline),
-    // 底色同樣指向 `--color-neutral-3`。對齊 Badge low / ProgressBar track SSOT。
-    const compactStaticBg = !progressBar ? 'bg-secondary' : ''
+    // Compact 靜態背景(AR20):無 status(= 無進度條)→ `bg-secondary`(= neutral-3)作「檔案已上傳 /
+    // 靜態列表」視覺區隔,跟「上傳中(有 progress bar)」對照;寫在下方 compact 的 cn() 裡(`!hasStatus &&`),
+    // 跟它的滑過配對同一次呼叫(見上方「滑過底色」段)。
+    // **為什麼用 semantic 的 bg-secondary、不直接寫 neutral 第 3 階的 primitive 名**:primitive token
+    // `--color-neutral-3` 沒經 `@theme inline` 橋接,拿它當 utility 會 silent 失效;`bg-secondary` 是 semantic
+    // token 橋接的 utility(見 `tokens/color/semantic.css`@theme inline),底色同樣指向 `--color-neutral-3`。
+    // 對齊 Badge low / ProgressBar track SSOT。
     // Primary row action 與 trailing actions 是 sibling controls，不把整列設成 role=button，
     // 因此不會形成 nested-interactive。透明 full-row button 只接 keyboard/focus；pointer
     // 仍由既有 row onClick 接手，保持 hit area 與 consumer callback contract 不變。
@@ -268,16 +355,37 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
             // hover 底色瞬間切換,不做過渡(user 2026-09-10 拍板「第三題改成全部瞬間」;SSOT = tokens/motion/motion.spec.md「hover 回饋不做過渡」)
             'group/row relative flex items-start gap-2 w-full text-body leading-compact',
             // 2026-09-07 H1g:限定只接下面那顆隱形整列鈕(keyboardPrimaryAction)。
-            // 原本裸寫 `has-[:focus-visible]` 不分對象,trailing action 的 <Button> 自帶
-            // ring(button.tsx:66)被聚焦時整列也跟著畫 → 一次互動兩個焦點框,
-            // 違反 focus-canonical「一個項目只有一個指示器」。
-            'has-[[data-row-focus-target]:focus-visible]:ring-2 has-[[data-row-focus-target]:focus-visible]:ring-ring',
+            // 原本裸寫 `has-[:focus-visible]` 不分對象,trailing action 的 <Button> 被聚焦時整列也跟著畫 →
+            // 一次互動兩個焦點框,違反 focus-canonical「一個項目只有一個指示器」。當時 <Button> 自帶
+            // ring;2026-09-16 a7b2be94 起它不再自帶焦點 class、改吃全域外描邊,但限定的理由不變。
+            // 幾何(2026-09-24 user 拍板「可以照你建議內描邊」):**內描邊**。原本寫的 `ring-2 ring-ring`
+            // 是 2026-09-07 就退役的第二套機制,只因閘的舊 regex 只認裸寫的 `focus-visible:ring-2`、
+            // 不認這裡的 `has-[…:focus-visible]:` 括號變體才活到今天(該洞同日已補,見
+            // scripts/focus-geometry-invariant.mjs R2)。
+            // **理由是結構性的**:拿到焦點的是下面那顆 `opacity-0` 的隱形整列鈕,它自己畫不出框,
+            // 指示器改畫在列上 —— 這是 focus-canonical「刻意不畫的唯一合法理由是指示器畫在別的元素上,
+            // 而且必須指得出承擔者」認可的形狀,承擔者就是本行所在的這個列 div。全域外描邊只作用在
+            // 「被聚焦的那個元素」身上,套不到非焦點的列;能掛在列上的只有 focus-ring-inset 與填色專用的
+            // focus-ring-inset-emphasis,列不是主色填色 → focus-ring-inset。
+            // **不是**靠四周淨空不足,也**不是**引用 item-anatomy「選中 × 互動疊加」表那句「列撐滿容器寬度,
+            // 左右沒有 2px 可以往外長」(那格的消費者清單沒有 FileItem):表單的列有圓角、列間 4–12px;
+            // 上傳管理器的列 2026-09-25 起鋪滿面板寬、列間 0(B12)—— 兩種幾何都用內描邊,理由只有上面那條結構性的
+            // (2026-09-24 審查抓到舊句把「淨空」當理由,勿寫回)。
+            // 也**不是**因為捲動容器會裁切 —— 捲動與否明文不進判準。
+            'has-[[data-row-focus-target]:focus-visible]:focus-ring-inset',
             // 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,
+            // avatar 作 item 邊界)。2026-06-03 codify rich-borderless(原僅 spec 旁註,consumer 自己移除)。form 保留 px-3 py-3 卡片內距。
+            surface === 'upload-manager'
+              // 上傳管理器的列(2026-09-25 待辦總帳 B12,推翻 2026-06-03「左右拿掉交給容器」):可點的列滑過底色要鋪到
+              // 面板左右邊,所以左右 gutter 改由列自己帶、面板 body 給 0(判準 = overlay-surface.spec.md「誰負責左右 gutter」);
+              // 值 = 原本面板給的 loose → 縮圖與文字的 x 不變。上下各 tight/2、面板 body 上下也給 tight/2、列間 0 ——
+              // 邊緣→縮圖、縮圖→縮圖仍是 tight,滑過底色上下各留 tight/2、不貼縮圖。
+              // 不加圓角:列鋪滿面板寬,圓角碰到面板的直邊會缺角(同 MenuItem 滿版列;AI 推導)。
+              ? 'px-[var(--layout-space-loose)] py-[calc(var(--layout-space-tight)/2)]'
+              : 'px-3 py-3 border border-divider rounded-md bg-surface',
+            onClick && 'cursor-pointer',
+            // 滑過(B12,見上方「滑過底色」段):上傳列平常透明 → 換成 neutral-hover;表單卡片平常是「底」bg-surface → 疊一層
+            onClick && (surface === 'upload-manager' ? 'hover:bg-neutral-hover' : 'hover:bg-interaction-hover'),
             className,
           )}
           onClick={onClick}
@@ -307,24 +415,49 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
       )
     }
 
-    // ── 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
+    // ── compact: bar absolute 底部 ──
+    // 內距單一來源(SSOT):progress bar 是 absolute 定位,其 left / right / bottom 必須跟列的內距「同源」——
+    // 左右取自 compactBarInset(與焦點框的挖空共用,見檔案上方),上下見下:
+    //   form:上下 py-2,bar 貼列底。
+    //   upload-manager(2026-09-25 待辦總帳 B12,推翻 2026-06-03 的「左右 0、交給面板」):可點的列滑過底色要鋪到面板
+    //     左右邊,所以左右改由列自己帶 loose(= 原本面板給的值,文字 x 不變)、面板 body 給 0。
+    //     上 tight/2、下 tight/2 + 0.5rem(0.5rem = 原 py-2 下緣那 8:文字↔bar 6 + bar 2),bar 離列底 tight/2;
+    //     面板 body 上下也給 tight/2、列間 0 → 邊緣→文字、bar→下一列文字、bar→邊緣仍全是 tight(與 06-03 同值),
+    //     滑過底色則上下各留 tight/2,bar 不貼底色邊。
+    const { padX: compactPadX, left: compactBarLeft, right: compactBarRight } = compactBarInset(surface)
+    const compactBarBottom = isUploadManager ? 'calc(var(--layout-space-tight) / 2)' : '0px'
+    const compactPadBlock = isUploadManager
+      ? { paddingTop: 'calc(var(--layout-space-tight) / 2)', paddingBottom: 'calc(var(--layout-space-tight) / 2 + 0.5rem)' }
+      : undefined
+    // 列底貼著進度條(form + 有 status)→ 框改畫在框圖層、進度條那段挖空;否則 undefined,框照舊畫在列上(見下方 className)
+    const ringCutout = fileItemRingCutoutStyle({ mode, surface, status })
     return (
       <div
         ref={ref}
         className={cn(
           // hover 底色瞬間切換,不做過渡(user 2026-09-10 拍板「第三題改成全部瞬間」;SSOT = tokens/motion/motion.spec.md「hover 回饋不做過渡」)
-          'group/row relative flex items-start gap-2 py-2 w-full text-body leading-compact rounded-md',
-          compactStaticBg,
-          // 2026-09-07 H1g:同 rich —— 只接隱形整列鈕,不接自帶 ring 的 trailing <Button>
-          'has-[[data-row-focus-target]:focus-visible]:ring-2 has-[[data-row-focus-target]:focus-visible]:ring-ring',
-          hoverClass,
+          'group/row relative flex items-start gap-2 w-full text-body leading-compact',
+          // form 的列是圓角膠囊 / 圓角列;upload-manager 的列鋪滿面板寬 → 不加圓角(同 rich,AI 推導),上下內距見上方 compactPadBlock
+          !isUploadManager && 'py-2 rounded-md',
+          !hasStatus && 'bg-secondary',
+          // 2026-09-07 H1g:同 rich —— 只接隱形整列鈕,不接同樣會畫框的 trailing <Button>;
+          // 幾何同 rich 的內描邊(結構性理由見上方那段)。
+          // **列底貼著進度條時,框畫在框圖層 ::before**(2026-09-26,file-item.spec.md「焦點框 × 貼著列底的進度條」)。
+          // 進度條是 absolute,本來就畫在框的**上面**,正好落在內描邊底邊那 2px 上 —— 但它沒有「蓋住」框:
+          // 軌道 --secondary 是半透明,框的藍從軌道透出來;填色 --info 又與框 --ring 同為 blue-6,與框黏成一條
+          // (實測聚焦時填色對軌道 1.10:1,平常 4.55:1;深色 1.17 / 4.04)。框圖層在進度條那一段(兩端各多 2px 縫)
+          // 挖空,露出真正的底:聚焦時進度條與平常逐像素相同,進度條的頭尾與框之間各隔一道底色的縫。
+          // upload-manager 的 bar 離列底 tight/2、碰不到框 → ringCutout 為 undefined,框照舊畫在列上。
+          ringCutout
+            ? [FILE_ITEM_RING_LAYER_CLASS, 'has-[[data-row-focus-target]:focus-visible]:before:focus-ring-inset']
+            : 'has-[[data-row-focus-target]:focus-visible]:focus-ring-inset',
+          onClick && 'cursor-pointer',
+          // 滑過(B12,見上方「滑過底色」段):有進度條的列平常透明 → 換成 neutral-hover;
+          // 靜態小膠囊平常是 bg-secondary → 換成它自己的下一階 secondary-hover(不借透明底的配對)
+          onClick && (hasStatus ? 'hover:bg-neutral-hover' : 'hover:bg-secondary-hover'),
           className,
         )}
-        style={{ paddingInline: compactPadX }}
+        style={{ paddingInline: compactPadX, ...compactPadBlock, ...ringCutout }}
         onClick={onClick}
         {...rowA11y}
         {...props}
@@ -340,12 +473,13 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
           {contentRow}
         </div>
 
-        {/* ProgressBar: absolute 底部。left/right 與 compactPadX 同源:
-            left = padX + icon + gap-2(0.5rem)對齊 label 首字;right = padX 收在 row 內緣。 */}
+        {/* ProgressBar: absolute 底部。left / right 取自 compactBarInset(與焦點框的挖空同源),bottom 與列內距同源:
+            left = padX + icon + gap-2(0.5rem)對齊 label 首字;right = padX 收在 row 內緣;
+            bottom = form 0(貼列底,聚焦時框在這一段挖空,見上方 className)/ upload-manager tight/2(B12,見上方內距段)。 */}
         {progressBar && (
           <div
-            className="absolute bottom-0"
-            style={{ left: `calc(${compactPadX}px + ${ICON_PX}px + 0.5rem)`, right: compactPadX }}
+            className="absolute"
+            style={{ left: compactBarLeft, right: compactBarRight, bottom: compactBarBottom }}
           >
             {progressBar}
           </div>
@@ -371,7 +505,7 @@ export const fileItemMeta = {
   tokens: {
     bg: ['bg-secondary', 'bg-surface'],
     fg: ['text-fg-muted', 'text-fg-secondary'],
-    ring: [],
+    ring: ['focus-ring-inset'],
   },
 } as const
 

package/src/components/FileUpload/file-upload.anatomy.stories.tsx

@@ -2,6 +2,7 @@
 import React from 'react'
 import type { Meta, StoryObj } from '@storybook/react'
 import { FileUpload } from './file-upload'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
 import { H3, Desc, Td, Th, TokenCell } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
 
 const meta: Meta = {
@@ -126,20 +127,15 @@ export const Inspector: Story = {
             hover 與 drag-over 視覺統一(純 border-driven)。預覽切換狀態後可對照右側 token 面板。
             (loading 已 deferred — 見上方 type 註解)
           </Desc>
-          <div className="flex gap-2 mb-4">
-            {(['idle', 'drag-over', 'disabled'] as StateKey[]).map((s) => (
-              <button
-                key={s}
-                onClick={() => setState(s)}
-                className={`px-3 py-1.5 text-caption rounded-md border ${
-                  state === s
-                    ? 'border-primary bg-primary-subtle text-primary'
-                    : 'border-border bg-surface text-foreground hover:bg-neutral-hover'
-                }`}
-              >
-                {s}
-              </button>
-            ))}
+          {/* 互斥切換消費 SegmentedControl(segmented-control.spec.md「何時用」2–5 個互斥選項)。取代手刻 pill:
+              它在不透明的 bg-surface 上換成透明底專用的 neutral-hover,深色主題滑過反而變暗(#1D1D1D→#141414,
+              color.spec.md 成對 token 錯配);SegmentedControl 底色恆為 surface、滑過只換邊框與字色 */}
+          <div className="mb-4">
+            <SegmentedControl size="sm" aria-label="State" value={state} onValueChange={(v) => setState(v as StateKey)}>
+              {(['idle', 'drag-over', 'disabled'] as StateKey[]).map((s) => (
+                <SegmentedControlItem key={s} value={s}>{s}</SegmentedControlItem>
+              ))}
+            </SegmentedControl>
           </div>
         </div>
 
@@ -440,7 +436,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">{"詳 `file-upload.spec.md` 「A11y 預設」段。摘要:\n\n- dropzone 使用 role=\"button\" + tabIndex=0(disabled/loading 時 -1)，Enter / Space 開啟選檔；accessible name 來自預設 Empty 文字或自訂 children / aria-label\n- button variant 使用原生 DS Button，accessible name 來自 buttonLabel\n- <input type=\"file\"> 以 hidden(display:none) 隱藏，移出無障礙樹；互動由當前 variant 的可見觸發元件承載"}</p>
+      <p className="whitespace-pre-line">{"詳 `file-upload.spec.md` 「A11y 預設」段。摘要:\n\n- dropzone 使用 role=\"button\" + tabIndex=0(disabled/loading 時 -1)，Enter / Space 開啟選檔；accessible name 來自預設 Empty 文字或自訂 children / aria-label\n- button variant 使用原生 DS Button，accessible name 來自 buttonLabel\n- <input type=\"file\"> 以 hidden(display:none) 隱藏，移出無障礙樹；互動由當前 variant 的可見觸發元件承載\n- 檔案清單(有 onRemove)= 一個 Tab 停靠點:↑↓ 換列、→ 進該列的移除鈕、← 回列、Tab 一下離開(待辦總帳 B9;按鍵表住 file-upload.spec.md「A11y 預設 › 檔案清單鍵盤」)"}</p>
     </div>
   ),
 }

package/src/components/FileUpload/file-upload.spec.md

@@ -62,6 +62,8 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 | `loading`（**deferred**）| `loading` prop 為 true | **Deferred:其唯一用途(無清單單檔/頭像替換)場景未定義,showcase 僅呈現 3-state(idle/drag-over/disabled);prop 在 tsx 保留供未來。** 行為:CircularProgress 取代內容;`cursor-progress`(不加 `pointer-events-none`,互動由 isBlocked guard 擋);aria-busy=true。有清單的 flow 進度一律走 FileItem 自身的 progress bar（uploading status）—— FileUpload 內建 list 仍 `surface=form`(dropzone 非獨立浮層 upload manager,見 file-item.spec.md「upload-manager 浮層面板 composition」)|
 | `disabled` | `disabled` prop 為 true | **語意 token(非 opacity — dashed outline surface 走 DS outline-disabled 慣例,3/4 世界級 Ant/Polaris/Carbon 用 token)**:`bg-disabled` 底 + 邊框不變色 + 文字/icon → `fg-disabled`(由 `<Empty disabled>` 控,icon-circle 維持 muted)+ `cursor-not-allowed`(移除 `pointer-events-none` 後生效)|
 
+**邊框變色瞬間切換、不過渡**(2026-09-26 待辦總帳 L9「全部瞬間」延伸到外框,user:「確定這樣才是一致設計語言就做」;同一次滑過底色瞬間、外框卻 0.15 秒 = 兩套手感;SSOT = `../../tokens/motion/motion.spec.md`「hover 回饋不做過渡」;2026-09-26 前是 `transition-colors` 0.15 秒)。
+
 **State 優先序**:`disabled > loading > drag-over > idle`。disabled 最硬(完全不可用),loading 次之(處理中,user 要等),drag-over 最柔(互動中),idle 預設。
 
 **loading vs disabled 的差異**:
@@ -112,7 +114,7 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 - `files`: uploaded / uploading 檔案清單(`FileUploadStatus[]`:id / name / size? / progress? / status? / description? / thumbnailSrc?)。傳入 → drop zone 下方渲染列表,每項經 `FileItem`(status 對應:uploading = progress bar / completed = ✓ / error = ✗);不傳 → 不顯示。consumer 持 state(progress / status),FileUpload 只負責渲染
 - `fileListMode`: 清單每項顯示模式;預設 `'compact'`(單行),`'rich'` 含 thumbnail / size / progress bar
 - `onRemove(id)`: 清單移除 callback;有值 → 每項右側顯示 X 移除鈕(ARIA label 由 `removeAriaLabel` 模板客製,預設「移除 {name}」),無 → view-only
-- 移除焦點:在 callback 前把 focus 交給下一項 remove button；沒有下一項則前一項；清單清空則回 FileUpload owner trigger（dropzone 或 button）。禁止 item unmount 後讓 focus 掉到 `body`。
+- 移除焦點:在 callback 前把 focus 交給下一項 remove button；沒有下一項則前一項；清單清空則回 FileUpload owner trigger（dropzone 或 button）。禁止 item unmount 後讓 focus 掉到 `body`。移除鈕不在 Tab 路上(見「A11y 預設」檔案清單鍵盤),但仍可由程式聚焦;焦點接力到哪一列,清單的 Tab 停靠點就跟到哪一列(2026-09-25 待辦總帳 B9)。
 - `variant` / `buttonLabel`: 見「兩種觸發外觀」段
 
 ---
@@ -150,6 +152,30 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 - `<input type="file">` 以 `className="hidden"`(`display:none`)隱藏，移出無障礙樹且不可聚焦；互動由當前 variant 的可見觸發元件承載。
 - **dropzone accessible name(name-from-content + custom children 例外)**:預設(未傳 children)時 name 來自 wrapper 內 `<Empty>` 的 title + description 文字,非 input 本身。若 consumer 傳入**只有 icon / branding 圖像、無可見文字**的 children，`role="button"` wrapper 會失去 accessible name；此時必須在 `<FileUpload>` root 傳 `aria-label`，或確保 children 含可見文字。
 
+### 檔案清單鍵盤(`files` + `onRemove`)= 一個 Tab 停靠點
+
+2026-09-25 待辦總帳 B9「路線乙」(`governance/planning/2026-09-25-interaction-and-hover-remediation.md`),user 逐字(附條件同意,條件查證成立記在該列):「確定建議符合我們一致的設計語言且不違背世界級的設計就照建議」。
+規則與一手依據住 `../../../ds-canonical/references/keyboard-model-canonical.md`「列上有小按鈕的一串」;本段只列本元件的按鍵表。2026-09-25 前:每一列的移除鈕各佔一站、沒有方向鍵。
+判定與執行 = `../../lib/roving-list-keyboard.ts`(2026-09-26 與 Sidebar / TreeView / Command 四份合一,待辦總帳〇節「按鍵規則合併」;判定表 `scripts/test-roving-list-keyboard.mjs`),本元件只提供「誰是列、列裡有哪些東西」;鍵盤處理掛在捕獲階段(同 Sidebar),`description` 裡放進來的選單鈕按 `↓` 也是換列(批次細節 X6)。列裡若有輸入框,它的方向鍵與空白鍵屬於它自己,`Tab` 仍一下離開。
+
+| 鍵 | 焦點在列上 | 焦點在這一列的按鈕上(移除鈕,或 `description` 裡的連結) |
+|---|---|---|
+| `↑` `↓` | 上 / 下一列,不繞回 | 回到上 / 下一列(焦點落在列上) |
+| `Home` `End` | 第一 / 最後一列 | 同左 |
+| `→` | 進這一列的第一顆按鈕(沒有就不動) | 下一顆;最後一顆停住 |
+| `←` | 不動 | 上一顆;第一顆 → 回到列 |
+| `Tab` / `Shift+Tab` | 一下離開清單 | 同左(先回到本列,再往下 / 往上走一站) |
+| `Enter` / `Space` | —(列本身沒有動作) | 啟動那顆按鈕 |
+
+- 別列的按鈕、這一列的按鈕都不在 Tab 路上(`tabIndex=-1`,`→` 才進得去);從外面 Tab 回來,落在上次停的那一列,沒停過(或那一列已被移除)→ 第一列。
+- 身分:容器 `role="grid"`(`aria-label="已上傳的檔案"`)、每列 `role="row"`(可聚焦,焦點框 = 內描邊 `focus-visible:focus-ring-inset`,同 FileItem 整列焦點框的幾何,`focus-canonical.md`「框怎麼畫」;**compact 清單裡有 `status` 的列**(進度條貼列底)框改畫在列自己的 `::before` 框圖層、在進度條那一段連同兩端各 2px 的縫挖空,列本身不畫全域外描邊 —— 框圖層與遮罩都由 FileItem 提供(`FILE_ITEM_RING_LAYER_CLASS` / `fileItemRingCutoutStyle`,挖的位置與進度條同源),規則與理由見 `../FileItem/file-item.spec.md`「焦點框 × 貼著列底的進度條」)、列的唯一子元素 FileItem `role="gridcell"`。
+- 為什麼是 grid:W3C listbox 模式明說選項裡不能互動,「To present a list of interactive elements, see the Grid Pattern」(<https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/listbox/listbox-pattern.html#L31-L33>)。
+- 列上多動作時用 grid / row、列的直接子元素是 gridcell:Fluent List「the list item roles should be `grid`, and `row` … each direct child of the `ListItem` component has a role `gridcell`」(<https://github.com/microsoft/fluentui/blob/d27922755bebae866d9ffe86b7da44c27ec801ee/packages/react-components/react-list/stories/src/List/ListDescription.md#L58>);React Aria GridList 同構(`role: 'grid'` <https://github.com/adobe/react-spectrum/blob/956ecbcb8803f0d0d5d5d973bb169d70c52aea02/packages/react-aria/src/gridlist/useGridList.ts#L192>、`'row'` / `'gridcell'` <https://github.com/adobe/react-spectrum/blob/956ecbcb8803f0d0d5d5d973bb169d70c52aea02/packages/react-aria/src/gridlist/useGridListItem.ts#L417-L462>)。
+- 容器與列用 `div`,不用 `ul` / `li`:W3C ARIA in HTML 的 `ul` 允許角色不含 grid(<https://www.w3.org/TR/html-aria/#el-ul>),`li` 在清單裡除了 listitem 不准換角色(<https://www.w3.org/TR/html-aria/#el-li>)。
+- **沒有 `onRemove` 的唯讀清單維持純 `ul` / `li`,不是焦點站**:列上沒有可操作的東西(`focus-canonical.md`「問題一」:不可操作 → 不可聚焦)。
+- 按鈕上的 `↑` `↓`、「先回到本列再離開」、唯讀清單不收成一站:AI 推導(`keyboard-model-canonical.md` 來源總帳);`Esc` 不規定(同該檔)。
+- 驗證:`file-upload.stories.tsx`「檔案清單鍵盤走法驗證」(test-only play)。
+
 ---
 
 ## 相關

package/src/components/FileUpload/file-upload.stories.tsx

@@ -139,6 +139,39 @@ export const FileListRemoveFocusContract = {
   },
 }
 
+// 鍵盤走法契約 probe(2026-09-25 待辦總帳 B9 路線乙;按鍵表 SSOT = file-upload.spec.md「A11y 預設」):
+// 有移除鈕的清單只佔一個 Tab 停靠點,↑↓ 換列、→ 進這一列的移除鈕、← 回列。只屬測試,不寄生在展示 story。
+export const FileListKeyboardContract = {
+  name: '檔案清單鍵盤走法驗證',
+  // 示範焦點是本則的主題(story-rules「示範 = 滑鼠使用者」):不放掉 play 造出的鍵盤焦點
+  parameters: { demoFocus: 'keep' },
+  tags: ['test-only'],
+  render: () => <FileListDemo />,
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement)
+    const grid = await canvas.findByRole('grid', { name: '已上傳的檔案' })
+    const rows = within(grid).getAllByRole('row')
+    // 整串只有一列在 Tab 路上;列裡的移除鈕都不在(-1,→ 才進得去)
+    await expect(rows.filter((row) => row.tabIndex === 0)).toHaveLength(1)
+    for (const button of within(grid).getAllByRole('button', { name: /^移除 / })) {
+      await expect(button).toHaveAttribute('tabindex', '-1')
+    }
+    // 從拖放區 Tab 一下進清單,落在第一列
+    canvas.getByRole('button', { name: /上傳附件/ }).focus()
+    await userEvent.tab()
+    await expect(rows[0]).toHaveFocus()
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(rows[1]).toHaveFocus()
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(within(rows[1]).getByRole('button', { name: '移除 cover-image.png' })).toHaveFocus()
+    await userEvent.keyboard('{ArrowLeft}')
+    await expect(rows[1]).toHaveFocus()
+    // 停靠點跟著焦點走:從外面 Tab 回來會落在這一列
+    await expect(rows[1]).toHaveAttribute('tabindex', '0')
+    await expect(rows[0]).toHaveAttribute('tabindex', '-1')
+  },
+}
+
 // beta.97 弱化 icon hover 一階的真實互動證據:
 // FileUpload 內建 files 清單自己渲染 remove Button,story 不以 className 模擬 hover。
 export const RemoveHoverState = {