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

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

@@ -0,0 +1,312 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { X } from 'lucide-react'
+import { FileUpload } from './file-upload'
+import { FileItem } from '@/design-system/components/FileItem/file-item'
+import { Button } from '@/design-system/components/Button/button'
+import { Field, FieldLabel } from '@/design-system/components/Field/field'
+import { Input } from '@/design-system/components/Input/input'
+
+const meta: Meta = {
+  title: 'Design System/Components/FileUpload/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers (inline, follow button.principles.stories.tsx) ────────────────────
+
+const Rule = ({
+  title,
+  note,
+  children,
+}: {
+  title: string
+  note?: string
+  children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && (
+      <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>
+    )}
+    <div className="flex flex-col gap-3 max-w-lg">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p
+    className={`text-footnote leading-normal ${
+      warn ? 'text-error font-medium' : 'text-fg-muted'
+    }`}
+  >
+    {children}
+  </p>
+)
+
+const noop = () => {}
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── WhenToUse — 何時使用 FileUpload ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse / DropzoneVsButtonRule(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 FileUpload 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/FileUpload/展示" name="單檔上傳"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">履歷 / 大頭貼等單檔上傳</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/FileUpload/展示" name="批次上傳"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">相簿照片 / 多檔附件批次上傳</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/FileUpload/展示" name="內建 files 屬性"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">上傳後直接顯示進度清單(內建 files 屬性)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/FileUpload/展示" name="自訂內容"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">品牌化上傳區 — 自訂 dropzone 內容</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見本頁 <code>UsageGuidance</code>「vs 近親」段)。</p>
+    </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div>
+      <Rule
+        title="❌ 不移除 dashed border(改成 solid)"
+        note="dashed 是世界級 dropzone 共識(Ant / Polaris / GitHub / Figma 皆然),視覺語意是「暫時、可放下」。solid border 暗示「永久邊界」,使用者會猶豫是否能拖入。"
+      >
+        <Label warn>⚠️ dashed border 是 affordance,不是裝飾——不可換成 solid</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不加 scale / shadow 等裝飾性 drag-over 信號"
+        note="drag-over 只用邊框顏色(border-primary-hover,底維持 surface 不變 bg)傳達狀態。加 scale 會讓區塊在拖放瞬間晃動、使用者滑鼠與 drop target 錯位;加 shadow 和元件 elevation 體系衝突。"
+      >
+        <div className="flex flex-col gap-2">
+          <div className="border-2 border-dashed border-primary-hover bg-surface rounded-md p-[var(--layout-space-loose)] text-center text-caption text-fg-muted">
+            ✓ 僅改邊框顏色(dashed primary-hover,底維持 surface)
+          </div>
+          <div className="border-2 border-dashed border-primary-hover bg-surface rounded-md p-[var(--layout-space-loose)] text-center text-caption text-fg-muted scale-105 shadow-[var(--elevation-200)]">
+            ✗ scale + shadow — 視覺噪音,與 elevation 系統衝突
+          </div>
+        </div>
+        <Label warn>⚠️ state 信號只走 color,不走 motion / elevation</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不用 FileUpload 做非檔案觸發"
+        note="「點擊開啟浮層」是 Popover / Dialog 的職責,不是 FileUpload。FileUpload = 檔案專用,避免 semantic 錯位。"
+      >
+        <Label warn>⚠️ 需要點擊開浮層 → 改用 Popover / Dialog,不要把 FileUpload 客製成選單</Label>
+      </Rule>
+    </div>
+
+      {/* vs 近親 — DropzoneVsButtonRule — 原 DropzoneVsButtonRule */}
+      <div>
+      <Rule
+        title="✅ 獨立上傳頁 / 主要動作 — 用 FileUpload dropzone"
+        note="拖放有價值(圖片、批次檔案、主要互動)且有足夠空間時才划算。對照:Figma 首頁 Import、Dropbox 上傳頁、Gmail compose 的附件區。"
+      >
+        <FileUpload
+          multiple
+          accept="image/*"
+          title="匯入設計檔案"
+          description="拖曳或點擊選取"
+          onUpload={noop}
+        />
+      </Rule>
+
+      <Rule
+        title='✅ 表單內 inline field — 用 FileUpload variant="button"'
+        note="form 裡和其他 field 並列時,大 dropzone 會破壞欄位節奏;variant=&quot;button&quot; 與 dropzone 共用同一套上傳邏輯(hidden input / accept / maxSize / onReject)。對照:Jira issue 附件按鈕、Stripe 發票上傳欄位——小按鈕不喧賓奪主。"
+      >
+        <div className="flex flex-col gap-3 w-full">
+          <Field>
+            <FieldLabel>申請人姓名</FieldLabel>
+            <Input placeholder="王小明" />
+          </Field>
+          <Field>
+            <FieldLabel>申請人身分證</FieldLabel>
+            <div className="flex items-center gap-2">
+              <Input className="flex-1" placeholder="A123456789" />
+              <FileUpload variant="button" buttonLabel="附上照片" accept="image/*" onUpload={noop} />
+            </div>
+          </Field>
+        </div>
+        <Label>↑ 「附上照片」= FileUpload variant="button"——與 dropzone 同上傳邏輯,只是觸發外觀緊湊化</Label>
+      </Rule>
+
+      <Rule
+        title="❌ form 裡塞大 dropzone"
+        note="上下欄位高度落差太大,使用者視覺節奏被打斷——這是 form field 不該出現的體積。"
+      >
+        <Label warn>⚠️ form 內 inline 上傳欄位,不要用大 dropzone(改 variant="button")</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const MultipleRule: Story = {
+  name: '多選',
+  render: () => (
+    <div>
+      <Rule
+        title="單檔(預設)— 頭像 / 履歷 / 封面照"
+        note="每個欄位只收一份檔案時用預設 multiple=false。世界級對照:LinkedIn 履歷上傳、Instagram 大頭貼、Notion page cover——使用者心智模型是「這個位置放一個檔案」。"
+      >
+        <FileUpload
+          accept="image/png,image/jpeg"
+          maxSize={2_000_000}
+          title="上傳大頭貼"
+          description="PNG / JPG,最大 2 MB"
+          onUpload={noop}
+        />
+        <Label>↑ 多拖幾個只取第一個,符合 Ant Upload.Dragger / Polaris DropZone 慣例</Label>
+      </Rule>
+
+      <Rule
+        title="multiple — 相簿 / 附件 / 批次匯入"
+        note="一次要收多份檔案時才 opt-in。世界級對照:Google Photos 匯入、Slack message 附件、Figma import assets——使用者預期「一次拖一批進來」。"
+      >
+        <FileUpload
+          multiple
+          accept="image/*"
+          title="批次上傳照片"
+          description="JPG / PNG / GIF,單檔最大 10 MB"
+          maxSize={10_000_000}
+          onUpload={noop}
+        />
+      </Rule>
+
+      <Rule
+        title="❌ 不把 multiple 當 default"
+        note="單檔場景(履歷 / 大頭貼 / 封面圖)才是 80% 的使用情境。預設多檔會讓 consumer 忘記限制、後端收到多份後再截斷,UX 破裂。"
+      >
+        <Label warn>
+          ⚠️ 以為「multiple 比較彈性」就預設開,實際反而讓單檔情境出 bug。明確 opt-in 才正確
+        </Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const DivisionOfLaborRule: Story = {
+  name: '與 FileItem 的職責分工',
+  render: () => {
+    const [files, setFiles] = React.useState([
+      { name: 'Q1-planning.pdf', description: '2.3 MB' },
+      { name: 'design-review.docx', description: '540 KB' },
+    ])
+    return (
+      <div>
+        <Rule
+          title="✅ FileUpload 觸發 + FileItem 顯示"
+          note="本範例走 consumer 自組清單:FileUpload 負責拖放偵測 + 觸發選檔,已上傳清單由 consumer 用 FileItem map 渲染。DS 同時支援第二條路——把清單交給 FileUpload 的 files prop 內建渲染(見下一則規則);兩條路都合法,差別只在觸發與清單狀態由誰持有,重點是都不重畫 FileItem 內部視覺。這正是 Notion / Slack / Figma 的附件 flow 做法。"
+        >
+          <FileUpload
+            multiple
+            title="加入附件"
+            description="任何檔案類型"
+            onUpload={(accepted) =>
+              setFiles((prev) => [
+                ...prev,
+                ...accepted.map((f) => ({
+                  name: f.name,
+                  description: `${(f.size / 1024 / 1024).toFixed(1)} MB`,
+                })),
+              ])
+            }
+          />
+          {files.length > 0 && (
+            <div className="flex flex-col gap-1">
+              {files.map((f, i) => (
+                <FileItem
+                  key={`${f.name}-${i}`}
+                  mode="compact"
+                  name={f.name}
+                  actions={
+                    <Button
+                      variant="text"
+                      size="xs"
+                      iconOnly
+                      startIcon={X}
+                      aria-label={`移除 ${f.name}`}
+                      onClick={() => setFiles((prev) => prev.filter((_, j) => j !== i))}
+                    />
+                  }
+                />
+              ))}
+            </div>
+          )}
+        </Rule>
+
+        <Rule
+          title="❌ 不在 FileUpload 裡自己重刻 FileItem primitives"
+          note="DS 提供兩條清單管理路徑:一是把清單交給 FileUpload 的 files prop,由它內部組合 FileItem 渲染;二是 consumer 自己用 files.map 逐項渲染 FileItem。兩條路都合法,真正禁止的是「自己重畫 FileItem 的內部視覺規格」——狀態圖示、縮圖比例、進度條、列排版都屬 FileItem 的 SSOT。世界級(Material / Ant / Carbon)也都是自己擁有清單、組合自家的 FileItem primitive,不另刻一套。"
+        >
+          <Label warn>⚠️ 要顯示清單 → 傳 `files` prop(內建)或自組 FileItem map;但不要自己重畫 FileItem 內部結構</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const ErrorFeedbackRule: Story = {
+  name: '檔案類型 + 最大尺寸 + 拒絕回呼 三配套',
+  render: () => {
+    const [errors, setErrors] = React.useState<string[]>([])
+    return (
+      <div>
+        <Rule
+          title="✅ 設 accept / maxSize 就一定要接 onReject"
+          note="accept / maxSize 擋下的檔案 FileUpload 靜默忽略,不會自動提示使用者。consumer 必須接 onReject 並顯示 Toast / Alert——否則使用者拖了檔案什麼都沒發生,會以為是 bug。"
+        >
+          <FileUpload
+            accept=".pdf,.doc,.docx"
+            maxSize={2_000_000}
+            title="上傳履歷(PDF / Word,最大 2 MB)"
+            description="試試拖入 JPG 或大於 2 MB 的檔案"
+            onUpload={() => setErrors([])}
+            onReject={(files, reason) => {
+              setErrors(
+                files.map((f) =>
+                  reason === 'size'
+                    ? `「${f.name}」超過 2 MB 上限`
+                    : `「${f.name}」格式不支援(需 PDF / Word)`,
+                ),
+              )
+            }}
+          />
+          {errors.length > 0 && (
+            <div className="rounded-md border border-error bg-error-subtle px-3 py-2 text-caption text-error-text">
+              {errors.map((msg, i) => (
+                <div key={i}>{msg}</div>
+              ))}
+            </div>
+          )}
+        </Rule>
+
+        <Rule
+          title="❌ 設了 accept / maxSize 卻不接 onReject"
+          note="使用者拖入不合格檔案後畫面毫無反應,會反覆嘗試最後放棄——這是沉默失敗,比明白拒絕還傷 UX。"
+        >
+          <Label warn>
+            ⚠️ 檔案限制必定配錯誤提示。onReject → Toast / 欄位下的 error message
+          </Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+

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

@@ -1,7 +1,13 @@
 ---
 component: FileUpload
 family: self-contained
-variants: {}
+variants:
+  dropzone:
+    when: "預設 — 大型 dashed 拖放區;「拖放有價值」+ 主要上傳區(drag + click)"
+    world-class: ["Ant Upload.Dragger", "Polaris DropZone"]
+  button:
+    when: "form 內單欄 / 空間省 / 與其他 field 並列 — 緊湊 Button 觸發(click-only)"
+    world-class: ["Ant Upload(button list)"]
 sizes: {}
 traits:
   - hasInteractiveStates
@@ -10,15 +16,14 @@ benchmark:
   - Polaris DropZone: github.com/Shopify/polaris/tree/main/polaris-react/src/components/DropZone
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # FileUpload 設計原則
 
 ## 定位
 
-FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點擊觸發檔案選取浮窗。負責「上傳觸發 + 拖放偵測」,不負責「已上傳檔案清單顯示」(那是 `FileItem` 的職責)。
+FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點擊觸發檔案選取浮窗。核心職責是「上傳觸發 + 拖放偵測」;它**不 own 單筆檔案列的視覺規格**(狀態圖示 / 縮圖 / 進度條 / 列排版屬 `FileItem` 的 SSOT),但**可 orchestrate 內建清單**——透過 `files` prop 內部組合 `FileItem` 渲染已上傳清單(dual-path,見「Props 行為」與「禁止事項」);consumer 自組 `FileItem` 清單亦合法。
 
-**實作基礎**:自建 — native HTML5 `<input type="file">` + drag-and-drop event(dragenter/dragover/dragleave/drop)+ DOM-level state 切換。無 external primitive,因為 Radix 沒 File Upload 對應 primitive,其他 UI kit 的 file upload 多數也是自建這層。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**實作基礎**:自建 — native HTML5 `<input type="file">` + drag-and-drop event(dragenter/dragover/dragleave/drop)+ DOM-level state 切換。選擇 native input 是為了保留檔案選取語意與瀏覽器安全邊界；drag state 只增補同一 input contract。
 
 **Layout Family**:非上述 family — self-contained primitive(獨立拖放區視覺,無 slot 結構)。
 
@@ -42,8 +47,8 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 | 場景 | 改用 | 原因 |
 |------|------|------|
 | 純文字輸入(無檔案) | `Input` / `Textarea` | FileUpload 只處理二進位檔 |
-| 單一檔案型欄位與其他 field 並列(form 內) | 小按鈕式 Button + hidden input | 不要在 form 中塞大塊 dropzone 破壞欄位節奏 |
-| 僅點擊選檔不需拖放 UX | 小 Button + hidden input | 大 dropzone 只在「拖放有價值」才划算 |
+| 單一檔案型欄位與其他 field 並列(form 內,空間省)| **`<FileUpload variant="button">`**(緊湊 Button 觸發) | 不要在 form 中塞大塊 dropzone 破壞欄位節奏;button variant 共用同上傳邏輯 + files 清單 |
+| 僅點擊選檔不需拖放 UX | **`<FileUpload variant="button">`** | 大 dropzone 只在「拖放有價值」才划算;button variant click-only |
 | 大量並列上傳多欄(頭像 × 10) | FileItem inline + inline Upload | dropzone 體積大,不適合密集並列 |
 
 ---
@@ -52,10 +57,10 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 
 | data-state | 情境 | 視覺 |
 |------------|------|------|
-| `idle`(預設) | 使用者未互動 | dashed border + surface 底,hover 切 neutral-hover |
-| `drag-over` | 使用者拖檔進入區塊內 | dashed border(primary)+ primary-subtle 底,icon 變 primary |
-| `loading` | `loading` prop 為 true(async 上傳 / 處理中) | 顯示 CircularProgress 取代預設內容;cursor-progress + pointer-events-none;aria-busy="true" |
-| `disabled` | `disabled` prop 為 true | opacity-disabled + pointer-events-none + cursor-not-allowed |
+| `idle`(預設) | 使用者未互動 | dashed `border-border`（**元件邊框 `--border`,非 `--divider` 分隔線**）+ surface 底 |
+| `hover` = `drag-over`（**統一,純 border-driven,對齊 Ant Dragger `colorPrimaryHover`**)| 游標懸停 / 拖檔進入 | **`border-primary-hover`**（只變邊框;2026-07-06 修 claim-vs-code drift——spec 一直宣稱 colorPrimaryHover、code 原寫 base,瞬時態歸 hover 階）+ 底維持 surface（不變 bg）。state 信號靠邊框,非底色;兩態同視覺 |
+| `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` 後生效)|
 
 **State 優先序**:`disabled > loading > drag-over > idle`。disabled 最硬(完全不可用),loading 次之(處理中,user 要等),drag-over 最柔(互動中),idle 預設。
 
@@ -64,15 +69,28 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 - **disabled** = 永久 / 條件性不可用,變灰 + cursor-not-allowed;user 知道「現在不能用」
 - 混用會破壞語意 — `loading=true` 時不要同時 `disabled=true`
 
-**為什麼用 dashed border**:世界級 dropzone 的共識(Ant / Polaris / GitHub drag-drop 都如此)——dashed 暗示「暫時、可放下」,solid border 暗示「永久邊界」。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**為什麼用 dashed border**:dashed 表示「可放下的暫時目標」，與永久容器使用的 solid boundary 區分；drag-active 再用 state token 提升可放置訊號。
 
 ---
 
-## children 插槽 vs 預設結構
+## 兩種觸發外觀(`variant`,2026-06-03 加)
+
+| variant | 觸發外觀 | 用途 | 拖放 |
+|---------|---------|------|------|
+| `dropzone`(預設)| 大型 dashed 拖放區(上述 4 狀態)| 「拖放有價值」+ 主要上傳區 | ✓ drag + click |
+| `button` | 緊湊 `<Button variant="tertiary" startIcon={Upload}>` | form 內單欄、空間省、與其他 field 並列 | click-only |
+
+**兩 variant 共用** `onUpload` / `onReject` / `accept` / `maxSize` / `files` 清單渲染;**都可放進 `<Field>` control slot**。對齊 Ant `Upload`(button list)vs `Upload.Dragger`(dropzone)。M21 prop-variant test 過(同上傳行為、不同觸發外觀、value 結構同 `File[]`)。
+
+**vs 直接用 `<Button>`**:Button 只有觸發外觀、無上傳邏輯(hidden input / accept / maxSize / onReject);任何檔案上傳一律 FileUpload,空間緊湊才選 `variant="button"`。
+
+> **FileUpload 常出現在 form**(`*Excel file` 欄位等)—— `variant` 只決定「觸發外觀大小」,**非「form vs 非 form」**;兩者都常在 form 裡。
+
+## dropzone children 插槽 vs 預設結構
 
 **預設**:直接渲染 `<Empty icon={Upload} title description />`——**重用 Empty 元件擁有的「icon + title + description 垂直居中」SSOT**(`../Empty/empty.spec.md`)。FileUpload 自己不重畫這套 layout,避免字體 / gap / icon 尺寸未來雙邊漂移。
 
-**覆寫**:傳 children 整個替換(不渲染 Empty)。典型場景:
+**覆寫**:`variant="dropzone"` 傳 children 時整個替換(不渲染 Empty)。`variant="button"` 固定渲染以 `buttonLabel` 命名的原生 DS Button，忽略 `children`、`title`、`description`。dropzone 典型客製場景:
 - 加檔案大小提示(「最大 10 MB」)
 - 加範例圖(「拖拉一張 JPG 進來」)
 - 加機構 branding(CompanyLogo + 客製文案)
@@ -84,20 +102,25 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 ## Props 行為
 
 - `onUpload(files)`: 使用者選取或拖放檔案,**過濾後**回傳 `File[]`
-- `onReject(files, reason)`: 被 `maxSize` / `accept` 擋下的檔案(consumer 可據此顯示 Toast / Alert)
+- `onReject(files, reason)`: 被擋下的檔案;`reason` 值域 `'size'`(超過 maxSize)/ `'type'`(不符 accept)。同次選取兩類各觸發一次。rejected 檔案的 UI 展示由 consumer 決定(Toast / Alert / FileItem `status="error"`),FileUpload 本身不渲染拒絕訊息
 - `multiple`: 預設 `false`(單檔);若 `false` 且使用者拖多檔,**只取第一個**交給 `onUpload`(不拋錯,符合 Ant Design 慣例)
 - `accept`: MIME filter,同時支援副檔名(`.pdf`)、通配(`image/*`)、完整 MIME(`application/pdf`)
 - `maxSize`: 單檔最大 bytes;超過靜默忽略(consumer 若要錯誤訊息,監聽 `onReject`)
-- `disabled`: 完全停用(pointer-events 關)
+- `disabled`: 完全停用(互動由 `isBlocked` guard 擋 + `cursor-not-allowed`;已移除 `pointer-events-none`,不再靠它擋)
+- `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`。
+- `variant` / `buttonLabel`: 見「兩種觸發外觀」段
 
 ---
 
 ## 禁止事項
 
 - ❌ **不在 FileUpload 裡自己重刻 FileItem primitives**(自畫 status icon / thumbnail / progress bar / row layout):那些是 `FileItem` 的 SSOT;FileUpload 若內建 list,**必 consume 既有 `<FileItem>`,不 replicate**
-  - 2026-04-24 canonical 明確化:DS 提供 dual path — (a) FileUpload own via `files` prop composing FileItem(見上「Post-upload file list」節)(b) consumer 自組 `{files.map(f => <FileItem ... />)}` 仍合法
+  - 2026-04-24 canonical 明確化:DS 提供 dual path — (a) FileUpload own via `files` prop composing FileItem(見「Props 行為」`files`)(b) consumer 自組 `{files.map(f => <FileItem ... />)}` 仍合法（2026-06-03 修:原引用「Post-upload file list」節為 phantom — 該節從未寫出,只剩 dangling reference）
   - 禁止的是「自己重畫 FileItem 視覺規格」(status 色 / thumbnail ratio / progress bar 等),不是「內建 list」本身
-  - 世界級對照:Material / Ant / Carbon 皆 FileUpload own list,用自家 FileItem primitive composing;本 DS 採相同 pattern(2026-04-24) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+  - FileUpload 擁有 upload lifecycle，row anatomy 則直接組合既有 FileItem primitive，避免平行維護第二套 file row
 - ❌ **不用 FileUpload 做非檔案觸發**(例:「點擊開啟浮層」——那是 Popover / Dialog)
 - ❌ **不移除 dashed border**(改 solid 會與「持久邊界」的視覺語意衝突,使用者直覺失靈)
 - ❌ **不把 multiple+bulk 當 default**:單檔是 80% 的場景(大頭照、單張附件),預設 `multiple=false` 讓使用者少一步判斷
@@ -105,12 +128,25 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 
 ---
 
+## 邊界案例
+
+- **超長檔名**:`files` 清單經 FileItem 渲染,label 單行 truncate(ellipsis)— 詳 `file-item.spec.md`「邊界案例」
+- **多檔拖放 + `multiple=false`**:只取過濾後第一個檔交給 `onUpload`,不拋錯(見「Props 行為」)
+- **空選取(0 檔)**:不觸發任何 callback;`files={[]}` 不渲染清單(等同不傳)
+- **maxSize / accept 全擋下**:`onUpload` 不觸發,只觸發 `onReject`
+- **同檔重選**(2026-07-05 D4):input value 於 dispatch 後清空 — 「上傳失敗修正後重選同檔」「刪除後重傳同檔」仍觸發 `onUpload`(瀏覽器對同路徑檔案不重發 change event,不清空則靜默無反應)
+- **拖曳滑過內部子元素**(2026-07-06 深度計數):pointer 移過 Empty 的 icon/title 時 drag-over 高亮不熄滅 — dragenter/dragleave 成對 +1/−1 深度計數,計數 > 0 即維持高亮;不依賴 `e.relatedTarget`(Safari/WebKit 的 dragleave relatedTarget 恆 null,guard 法必失效,故已於 2026-07-06 廢棄換深度計數),避免經典 drag-flicker
+- **Disabled / loading 時拖檔 drop**(2026-07-05 D4):操作被吞掉 — 仍 `preventDefault` 擋瀏覽器預設「在當前 tab 開啟被丟檔案」的整頁導航,`onUpload` 不觸發
+- Disabled / loading 見「四狀態視覺」;dark mode / density 由 semantic token 自動處理
+
+---
+
 ## A11y 預設
 
-- `role="button"` + `tabIndex=0`(disabled 時 `-1`)
-- Enter / Space 鍵觸發檔案選取浮窗(模擬 click)
-- `aria-disabled={true}` 當 disabled
-- `<input type="file">` 隱藏但仍可被 screen reader 偵測到;Label 透過 container 文字(title + description)提供情境
+- **dropzone**:`role="button"` + `tabIndex=0`(disabled 或 loading 時 `-1`)，Enter / Space 開啟檔案選取浮窗，disabled 時帶 `aria-disabled=true`。
+- **button**:使用原生 DS `<Button>`，鍵盤與 disabled 語意由 button 元素提供；accessible name 來自 `buttonLabel`，不使用 dropzone 的 children/name-from-content 規則。
+- `<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 含可見文字。
 
 ---
 
@@ -118,6 +154,12 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 
 - `../FileItem/file-item.spec.md` — 已上傳檔案的 list row 渲染(配對元件)
 - `../Empty/empty.spec.md` — 本元件預設 children 消費,「icon + title + description」SSOT
-- `../Button/button.spec.md` — 小按鈕式上傳的替代方案
-- Ant Design `Upload.Dragger` 原始參考 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- Polaris `DropZone` 原始參考 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- `../Button/button.spec.md` — `variant="button"` 消費的觸發元件(見「兩種觸發外觀」)
+- 本 spec 的 Anatomy / 狀態表與 `file-upload.tsx` — canonical authority
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `empty.spec.md`
+- `file-item.spec.md`