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

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

@@ -0,0 +1,219 @@
+// @story-history: hasInteractiveStates 的 Disabled / States 由 anatomy.stories.tsx StateBehavior auto-compile owns(2026-05-15 F-migration);showcase 層展示真實上傳 / 自訂內容情境。
+import type { Meta } from '@storybook/react'
+import { expect, userEvent, within } from '@storybook/test'
+import { useState } from 'react'
+import { Image as ImageIcon, 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 { Empty } from '@/design-system/components/Empty/empty'
+
+const meta: Meta<typeof FileUpload> = {
+  title: 'Design System/Components/FileUpload/展示',
+  tags: ['autodocs'],
+  component: FileUpload,
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '接收拖放或檔案選擇並呈現上傳入口，可配合 FileItem 管理進度與錯誤。產品需要新增本機檔案到工作流時使用；既有檔案的預覽改用 FileViewer。' } },
+  },
+}
+export default meta
+
+const noop = () => {}
+
+// 單檔上傳:履歷(PDF / Word),5 MB 上限 — LinkedIn / 104 Job 慣例
+export const ResumeUpload = {
+  name: '單檔上傳',
+  render: () => (
+    <div className="max-w-lg">
+      <FileUpload
+        accept=".pdf,.doc,.docx"
+        maxSize={5_000_000}
+        title="上傳你的履歷"
+        description="PDF / Word 格式,單檔最大 5 MB"
+        onUpload={noop}
+        onReject={noop}
+      />
+    </div>
+  ),
+}
+
+// 批次上傳:相簿匯入 — Figma / Google Photos / Instagram 慣例
+export const BulkImageUpload = {
+  name: '批次上傳',
+  render: () => {
+    const [files, setFiles] = useState<File[]>([])
+    return (
+      <div className="max-w-lg flex flex-col gap-3">
+        <FileUpload
+          multiple
+          accept="image/*"
+          title="拖曳相片到這裡,或點擊選取"
+          description="支援 JPG / PNG / GIF,可一次選多張"
+          onUpload={(accepted) => setFiles((prev) => [...prev, ...accepted])}
+        />
+        {files.length > 0 && (
+          // Compact FileItem 上傳完成有 bg-secondary 靜態底色 → 必 `gap-1`(4px)防貼邊
+          // (見 file-item.spec.md「List wrapper canonical」+ item-anatomy「連續 item 貼邊合法性」)
+          <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>
+        )}
+      </div>
+    )
+  },
+}
+
+// WithUploadedList retired 2026-04-24(Dim 24 redundancy):教同樣「upload → list display」flow
+// WithFileList(DS-canonical built-in `files` prop),保留 display story 重複 principle。Consumer
+// 不傳 `files` 則自動回 pre-2026-04-24 consumer-composed pattern(無須 story 示範「不傳 prop」)。
+
+// 2026-04-24 canonical:內建 `files` prop — FileUpload own success state display
+const FileListDemo = () => {
+    type UploadItem = { id: string; name: string; size?: number; status?: 'uploading' | 'completed' | 'error'; progress?: number; description?: string }
+    const [items, setItems] = useState<UploadItem[]>([
+      { id: '1', name: '2026-Q1-report.pdf', size: 2_500_000, status: 'completed' },
+      { id: '2', name: 'cover-image.png', size: 1_200_000, status: 'uploading', progress: 68 },
+      { id: '3', name: 'malware.exe', status: 'error', description: '檔案類型不允許' },
+    ])
+    return (
+      <div className="max-w-lg">
+        <FileUpload
+          multiple
+          title="上傳附件"
+          description="最多 20 MB / 檔"
+          maxSize={20_000_000}
+          files={items}
+          fileListMode="compact"
+          onRemove={(id) => setItems((prev) => prev.filter((i) => i.id !== id))}
+          onUpload={(accepted) =>
+            setItems((prev) => [
+              ...prev,
+              ...accepted.map((f, i) => ({
+                id: `new-${Date.now()}-${i}`,
+                name: f.name,
+                size: f.size,
+                status: 'completed' as const,
+              })),
+            ])
+          }
+        />
+      </div>
+    )
+}
+
+export const WithFileList = {
+  name: '內建 files 屬性',
+  render: () => <FileListDemo />,
+}
+
+// Roving-focus 契約 probe:移除檔案後焦點落到下一個移除鈕。破壞性互動(移除
+// 檔案)只屬測試,不得寄生在 reader-facing 展示 story(同 PeoplePicker
+// 2026-08-05 anchor;story-rules「Technical probe visibility」canonical)。
+export const FileListRemoveFocusContract = {
+  name: '移除焦點接力驗證',
+  tags: ['test-only'],
+  render: () => <FileListDemo />,
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement)
+    await userEvent.click(await canvas.findByRole('button', { name: '移除 2026-Q1-report.pdf' }))
+    await expect(await canvas.findByRole('button', { name: '移除 cover-image.png' })).toHaveFocus()
+  },
+}
+
+// beta.97 弱化 icon hover 一階的真實互動證據:
+// FileUpload 內建 files 清單自己渲染 remove Button,story 不以 className 模擬 hover。
+export const RemoveHoverState = {
+  name: '移除檔案懸停狀態',
+  tags: ['test-only'],
+  render: () => (
+    <div className="max-w-lg">
+      <FileUpload
+        title="上傳季度報告"
+        description="PDF,單檔最大 20 MB"
+        files={[
+          {
+            id: 'quarterly-report',
+            name: '2026-Q2-季度報告.pdf',
+            size: 2_500_000,
+            status: 'completed',
+          },
+        ]}
+        fileListMode="compact"
+        onRemove={noop}
+        onUpload={noop}
+      />
+    </div>
+  ),
+  play: async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+    const canvas = within(canvasElement)
+    const remove = await canvas.findByRole('button', { name: '移除 2026-Q2-季度報告.pdf' })
+    remove.setAttribute('data-visual-hover-target', '')
+  },
+}
+
+// children 覆寫:Figma 匯入資產客製文案 / 品牌 logo
+export const CustomChildren = {
+  name: '自訂內容',
+  render: () => (
+    <div className="max-w-lg">
+      {/* children 覆寫的正確用法:換 icon(FileUpload 無 icon prop)時仍**消費 Empty SSOT** —
+          字級 / icon 48 / 間距全跟 Empty 不漂移。只改文字用 title/description prop 即可、不必 children;
+          children 是給「換 icon」或「加 icon+title+desc 以外的元素(品牌 logo / 格式 chips)」用。
+          ❌ 反 pattern:hand-build 自訂字級/icon尺寸/間距(= 偏離 Empty 設計語言)。 */}
+      <FileUpload accept="image/*,.svg,.fig" multiple onUpload={noop}>
+        <Empty
+          icon={ImageIcon}
+          title="匯入你的設計資產"
+          description="支援 SVG / PNG / Figma 檔案 · 一次最多 50 個"
+        />
+      </FileUpload>
+    </div>
+  ),
+}
+
+// variant="button":表單內緊湊上傳(*Excel file 欄位場景)— 大 dropzone 太重時用按鈕觸發,
+// 檔案清單在按鈕下方(form compact 靜態)。2026-06-03 加 — FileUpload 常出現在 form。
+export const ButtonVariant = {
+  name: '按鈕觸發(表單內)',
+  render: () => {
+    type Item = { id: string; name: string; size?: number; status?: 'completed' }
+    const [items, setItems] = useState<Item[]>([
+      { id: '1', name: 'UXP T-Phone.xlsx', size: 1_800_000, status: 'completed' },
+    ])
+    return (
+      <div className="max-w-md">
+        <FileUpload
+          variant="button"
+          buttonLabel="Choose Excel file" // i18n-allow: story label
+          accept=".xls,.xlsx,.csv"
+          files={items}
+          fileListMode="compact"
+          onRemove={(id) => setItems((prev) => prev.filter((i) => i.id !== id))}
+          onUpload={(accepted) =>
+            setItems((prev) => [
+              ...prev,
+              ...accepted.map((f, i) => ({ id: `n-${Date.now()}-${i}`, name: f.name, size: f.size, status: 'completed' as const })),
+            ])
+          }
+        />
+      </div>
+    )
+  },
+}

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

@@ -11,19 +11,23 @@ import { Button } from '@/design-system/components/Button/button'
  * FileUpload — 拖放 / 點擊上傳區塊
  *
  * 世界級對照:Ant Design `Upload.Dragger`、Polaris `DropZone`、Material community MUI-File-Input。
- * 與本 DS 既有 FileItem(顯示已上傳檔案)配對 — 這裡 own「上傳觸發 + 拖放偵測」,
- * 上傳後的檔案清單顯示交給 consumer 用 FileItem 渲染。
+ * 與本 DS 既有 FileItem(顯示已上傳檔案)配對 — 這裡 own「上傳觸發 + 拖放偵測」；
+ * 上傳後可由 `files` 走內建 FileItem 清單，也可由 consumer 自行組合 FileItem。
  *
- * ── 4 狀態 ──
- * idle     (default) — border-dashed border-divider  bg-surface
- * drag-over         — border-dashed border-primary  bg-primary-subtle
- * loading           — 上傳中(async)顯示 CircularProgress,阻擋新互動
- * disabled          — opacity-disabled pointer-events-none
+ * ── 4 狀態(2026-06-03 修正)──
+ * idle     (default) — border-dashed border-border  bg-surface
+ * hover = drag-over  — border-primary-hover(統一,純 border-driven,底維持 surface;2026-07-06 對齊 Ant colorPrimaryHover)
+ * loading            — CircularProgress;cursor-progress(無 pointer-events-none)
+ * disabled           — bg-disabled + 文字 fg-disabled(語意 token,非 opacity)+ cursor-not-allowed
  *
- * ── children 插槽 ──
+ * ── variant ──
+ * dropzone(預設)大拖放區 + drag;button 緊湊 Button 觸發(form-friendly,click-only)
+ *
+ * ── dropzone children 插槽 ──
  * 預設渲染 `<Empty icon={Upload} title description />` — 重用 Empty 元件 own
  * 的「icon + title + description 垂直居中」SSOT 避免視覺漂移。Empty 改字體 /
  * gap / icon 尺寸時 FileUpload 自動跟進。若 consumer 傳 children 則整個覆寫。
+ * button variant 只顯示以 `buttonLabel` 命名的原生 DS Button，忽略此展示插槽。
  *
  * ── API ──
  * onUpload: 使用者選取或拖放檔案時觸發,回傳 File[](至少 1 個)。
@@ -58,27 +62,36 @@ export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElemen
   accept?: string
   maxSize?: number
   disabled?: boolean
+  /**
+   * 觸發外觀(2026-06-03 加,M21 prop-variant + Ant `Upload`(button)/`Upload.Dragger`(dropzone)先例):
+   * - `dropzone`(預設):大拖放區 + 點擊,支援 drag-and-drop。
+   * - `button`:緊湊 Button 觸發(form-friendly,省空間),click-only(無拖放區)。
+   * 兩者共用 onUpload / onReject / files 清單渲染;都可放進 Field control slot。
+   */
+  variant?: 'dropzone' | 'button'
+  /** `variant="button"` 的按鈕文字(預設「Choose file」)。 */
+  buttonLabel?: string
   /**
    * Loading 狀態(async 上傳 / 伺服器處理中)。
-   * - 顯示 CircularProgress 取代預設 Empty 內容
-   * - 阻擋新點擊 / drag 事件(避免 double-submit)
+   * - 2026-06-03 **deferred**:其唯一用途(無清單單檔 / 頭像替換)場景尚未定義,故已從 3-state showcase
+   *   移除、不作為當前 feature 呈現;prop 保留供未來該場景。有清單的上傳進度走 FileItem 自身 progress bar(status=uploading）。
+   * - 顯示 CircularProgress 取代預設 Empty 內容;`cursor-progress`;互動由 handleClick/handlers 的 isBlocked guard 擋
    * - 宣告 `aria-busy="true"` 讓 screen reader 感知處理中
-   * - Consumer 負責在上傳完成後自己切回 `loading={false}`
    */
   loading?: boolean
   /** Loading 狀態的文字標題(預設「上傳中…」) */
   loadingTitle?: string
-  /** 標題文字(預設「Click or drag file here to upload」) */
+  /** dropzone 標題文字(預設「Click or drag file here to upload」；button variant 忽略) */
   title?: string
-  /** 說明文字(預設「Support for a single or bulk upload」) */
+  /** dropzone 說明文字(預設依 multiple 切換；button variant 忽略) */
   description?: string
-  /** 若傳入 children,覆寫預設 Empty 結構 */
+  /** dropzone:若傳入 children,覆寫預設 Empty 結構；button variant 忽略 */
   children?: React.ReactNode
   /**
    * Uploaded / uploading 檔案清單。傳入 → FileUpload 在 drop zone 下方渲染列表。
    * 不傳 → 不顯示(consumer 可自行用 FileItem 組成,pre-2026-04-24 行為)。
-   * 每項有 status 狀態會對應 icon:
-   *   - `uploading`:CircularProgress(+ progress bar 若 progress 給)
+   * 每項由 FileItem 渲染,status 狀態對應視覺:
+   *   - `uploading`:linear ProgressBar(via FileItem;rich mode 另顯示 {progress}%)
    *   - `completed`:綠色 ✓(success 狀態視覺確認)
    *   - `error`:紅色 ✗(+ description 顯示錯誤訊息)
    */
@@ -91,6 +104,15 @@ export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElemen
   removeAriaLabel?: (name: string) => string
 }
 
+function focusAfterFileRemoval(current: HTMLButtonElement) {
+  const list = current.closest('ul')
+  const buttons = list ? Array.from(list.querySelectorAll<HTMLButtonElement>('[data-collection-remove]')) : []
+  const index = buttons.indexOf(current)
+  const next = buttons[index + 1] ?? buttons[index - 1]
+  const owner = list?.parentElement?.querySelector<HTMLElement>('[data-file-upload-owner]')
+  ;(next ?? owner)?.focus()
+}
+
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
   (
@@ -101,6 +123,8 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
       accept,
       maxSize,
       disabled = false,
+      variant = 'dropzone',
+      buttonLabel = 'Choose file', // i18n-allow: DS default; consumer override via buttonLabel prop
       loading = false,
       loadingTitle = '上傳中…', // i18n-allow: DS default; consumer override via loadingTitle prop
       title = 'Click or drag file here to upload', // i18n-allow: DS default; consumer override via title prop
@@ -118,6 +142,10 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
   ) => {
     const inputRef = React.useRef<HTMLInputElement>(null)
     const [isDragOver, setDragOver] = React.useState(false)
+    // drag enter/leave 深度計數(react-dropzone / Mantine Dropzone 同款):跨進內部子元素時
+    // 瀏覽器發「子 dragenter → 外層 dragleave」成對事件,+1/−1 抵銷後計數仍 > 0 = 沒離開。
+    // 不依賴 e.relatedTarget —— Safari/WebKit 的 dragleave relatedTarget 恆 null,guard 法必失效。
+    const dragDepth = React.useRef(0)
 
     const filterAndDispatch = (files: FileList | null) => {
       if (!files || files.length === 0) return
@@ -143,7 +171,9 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
     }
 
     const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
-      if (!disabled) inputRef.current?.click()
+      // 2026-06-03 Q4:guard `!disabled && !loading`(= !isBlocked)。loading 時也擋點擊防 double-submit
+      // (原只 guard !disabled,靠 pointer-events-none 擋 loading;移除 pointer-events-none 後改這裡 guard)。
+      if (!disabled && !loading) inputRef.current?.click()
       onClick?.(e)
     }
 
@@ -156,11 +186,13 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
     const fileListNode = hasFiles ? (
       <ul
         className={cn(
-          // stack vertically with consistent gap;bg-surface 在容器外的 chrome / consumer bg 之上
-          'flex flex-col gap-2 w-full',
-          'mt-3',
+          'flex flex-col w-full',
+          // 2026-06-03 gap SSOT:列間 gap + control→list gap(mt)由「item 有無邊框」單一規則決定,
+          // 同值貫穿整個垂直堆疊 — rich(form surface = border card)→ 8px;compact(borderless/bg-pill)→ 4px。
+          // 消費 FileItem「List wrapper canonical」(file-item.spec.md),取代原硬寫 gap-2 / mt-3(不分 mode)。
+          fileListMode === 'rich' ? 'gap-2 mt-2' : 'gap-1 mt-1',
         )}
-        aria-label="Uploaded files"
+        aria-label="已上傳的檔案"
       >
         {files!.map((f) => (
           <li key={f.id} className="list-none">
@@ -175,18 +207,20 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
                 onRemove ? (
                   // Collection remove(per-file)— 不是 dismiss surface,故不套 `dismiss` prop。
                   // 視覺與 dismiss 一致(text variant + fg-muted dim)— 對齊 inline-action.spec.md
-                  // 「Dismiss canonical — X close only」L249-251:onRemove callback 不觸發 dismiss prop。
+                  // 「Dismiss canonical — X close only」+「dismiss prop 觸發條件」段:onRemove callback 不觸發 dismiss prop。
                   <Button
                     iconOnly
                     variant="text"
                     size="xs"
                     startIcon={X}
                     aria-label={removeAriaLabel(f.name)}
+                    data-collection-remove
                     onClick={(e) => {
                       e.stopPropagation()
+                      focusAfterFileRemoval(e.currentTarget)
                       onRemove(f.id)
                     }}
-                    className="text-fg-muted hover:text-foreground"
+                    className="text-fg-muted hover:text-fg-secondary"
                   />
                 ) : undefined
               }
@@ -198,7 +232,44 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
 
     return (
       <div ref={ref} className={cn('w-full', hasFiles && 'flex flex-col')}>
+      {variant === 'button' ? (
+        // ── button variant:緊湊觸發(form-friendly,省空間),click-only(無拖放區)──
+        // consumer onClick 在此 wrapper div 承載(type = MouseEvent<HTMLDivElement>,對齊 FileUploadProps
+        // extends HTMLAttributes<HTMLDivElement>)。Button 觸發開檔會冒泡至此 → 同時觸發 consumer handler。
+        // 2026-07-17 修:onClick 於 L128 destructure 後未再 compose,button variant 靜默丟失公開 DOM prop
+        // (dropzone variant 經 handleClick 的 onClick?.(e) 正確 compose,button variant 漏接)。
+        <div className={className} onClick={onClick} {...props}>
+          <input
+            ref={inputRef}
+            type="file"
+            className="hidden"
+            multiple={multiple}
+            accept={accept}
+            disabled={disabled}
+            onChange={(e) => {
+              // 2026-07-05 D4:dispatch 後清空 value — 瀏覽器對同路徑檔案不重發 change,
+              // 不清空則「失敗修正後重選同檔 / 刪除後重傳同檔」靜默無反應
+              filterAndDispatch(e.target.files)
+              e.target.value = ''
+            }}
+          />
+          <Button
+            data-file-upload-owner
+            variant="tertiary"
+            startIcon={UploadIcon}
+            loading={loading}
+            disabled={disabled}
+            aria-busy={loading || undefined}
+            onClick={() => {
+              if (!disabled && !loading) inputRef.current?.click()
+            }}
+          >
+            {buttonLabel}
+          </Button>
+        </div>
+      ) : (
       <div
+        data-file-upload-owner
         role="button"
         tabIndex={isBlocked ? -1 : 0}
         aria-disabled={disabled || undefined}
@@ -215,39 +286,54 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
         onDragEnter={(e) => {
           if (isBlocked) return
           e.preventDefault()
+          // 2026-07-06 深度計數升級(user 實測抓到「拖入約一秒高亮熄滅」):游標從邊緣飄到中央
+          // 跨進 Empty icon/標題那刻,瀏覽器發「子 dragenter → 外層 dragleave」→ 舊版無 guard 直接
+          // 熄滅;2026-07-05 的 relatedTarget guard 只救 Chrome(Safari/WebKit dragleave 的
+          // relatedTarget 恆 null → guard 失效)。深度計數不依賴 relatedTarget,跨瀏覽器穩定。
+          dragDepth.current += 1
           setDragOver(true)
         }}
         onDragLeave={(e) => {
           if (isBlocked) return
           e.preventDefault()
-          setDragOver(false)
+          dragDepth.current = Math.max(0, dragDepth.current - 1)
+          if (dragDepth.current === 0) setDragOver(false)
         }}
         onDragOver={(e) => {
-          if (isBlocked) return
+          // 2026-07-05 D4:blocked 時仍先 preventDefault — dragover 未取消 = 非合法 drop target,
+          // 瀏覽器 default 會在當前 tab 直接開啟被丟檔案(整頁導航,app 狀態全失);吞掉操作而非讓瀏覽器接管
           e.preventDefault()
         }}
         onDrop={(e) => {
-          if (isBlocked) return
+          // 2026-07-05 D4:preventDefault 先於 isBlocked guard — 同 dragover,擋瀏覽器開檔導航
           e.preventDefault()
+          if (isBlocked) return
+          dragDepth.current = 0 // drop 結束整輪拖曳,計數歸零(下一輪從乾淨狀態起算)
           setDragOver(false)
           filterAndDispatch(e.dataTransfer.files)
         }}
         className={cn(
           // 寬度 w-full 填滿 consumer 容器(user 明示「寬度填滿」);高度由 padding + 內容物決定(不固定 h)
           'flex flex-col items-center justify-center gap-2 text-center w-full',
-          // 對稱 padding p-[var(--layout-space-loose)]:四邊等距,density-aware(md=24px / lg=32px),對齊 DS chrome padding canonical。
+          // 對稱 padding p-[var(--layout-space-loose)]:四邊等距,density-aware(md=16px / lg=24px),對齊 DS chrome padding canonical。
           // 不再硬寫 px-6 py-10(不對稱+非 token)。內容物(icon + title + description)垂直堆疊由 gap-2 控制
           'rounded-md border-2 border-dashed p-[var(--layout-space-loose)]',
           'cursor-pointer transition-colors',
           'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
-          // idle
-          'border-divider bg-surface hover:bg-neutral-hover',
-          // drag-over
-          'data-[state=drag-over]:border-primary data-[state=drag-over]:bg-primary-subtle data-[state=drag-over]:hover:bg-primary-subtle',
-          // loading(阻擋新互動但不 opacity-disabled — 避免跟 disabled 視覺撞,保持「處理中」語意)
-          'data-[state=loading]:cursor-progress data-[state=loading]:pointer-events-none',
-          // disabled
-          'data-[state=disabled]:opacity-disabled data-[state=disabled]:pointer-events-none data-[state=disabled]:cursor-not-allowed',
+          // idle:--border(元件邊框,非 --divider 分隔線 — 2026-06-03 Q2 token 修正)+ surface 底
+          'border-border bg-surface',
+          // hover = drag-over 統一(2026-06-03 Q2-A 純 border-driven,對齊 Ant Dragger colorPrimaryHover):
+          // 兩者都 → primary-hover 邊框(2026-07-06 修:註解與 spec 一直宣稱 colorPrimaryHover、
+          // code 卻寫 base = claim-vs-code 反向 drift;瞬時態歸 hover 階,雙向全掃唯一 B 類違規),
+          // 底色維持 surface(不變 bg)。state 信號靠邊框,非底色。
+          // 2026-06-11 R2(M5 狀態疊加):hover 變 primary 僅限 idle —— disabled/loading 維持原邊框(spec「disabled 邊框不變色」;dropzone 狀態機無 error 態,error 屬 files 清單 FileItem status)
+          'data-[state=idle]:hover:border-primary-hover data-[state=drag-over]:border-primary-hover',
+          // loading(2026-06-03 Q4:移除 pointer-events-none — 它會讓 cursor-progress 失效;
+          // 互動已由 handleClick + drag/key handlers 的 isBlocked guard 擋,不需 pointer-events-none)
+          'data-[state=loading]:cursor-progress',
+          // disabled(2026-06-03 Q3:語意 token 非 opacity — dashed outline surface 走 DS outline-disabled 慣例;
+          // bg→disabled,border 不變色,文字/icon 由 Empty disabled 控;cursor-not-allowed 現在生效)
+          'data-[state=disabled]:bg-disabled data-[state=disabled]:cursor-not-allowed',
           className,
         )}
         {...props}
@@ -259,23 +345,30 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
           multiple={multiple}
           accept={accept}
           disabled={disabled}
-          onChange={(e) => filterAndDispatch(e.target.files)}
+          onChange={(e) => {
+            // 2026-07-05 D4:dispatch 後清空 value — 瀏覽器對同路徑檔案不重發 change,
+            // 不清空則「失敗修正後重選同檔 / 刪除後重傳同檔」靜默無反應
+            filterAndDispatch(e.target.files)
+            e.target.value = ''
+          }}
         />
         {loading ? (
-          <Empty
-            icon={<CircularProgress size={48} />}
-            title={loadingTitle}
-          />
+          <div role="status" aria-label={loadingTitle} className="flex flex-col items-center text-center">
+            <div className="mb-4"><CircularProgress size={48} /></div>
+            <span aria-hidden className="text-body-lg font-medium text-foreground">{loadingTitle}</span>
+          </div>
         ) : (
           children ?? (
             <Empty
               icon={UploadIcon}
               title={title}
               description={description}
+              disabled={disabled}
             />
           )
         )}
       </div>
+      )}
       {fileListNode}
       </div>
     )
@@ -310,14 +403,16 @@ export const fileUploadMeta = {
   component: 'FileUpload',
   family: null, // non-family composite / overlay / layout
   variants: {
-
+    dropzone: { purpose: '大型 dashed 拖放區(預設)— 拖放有價值 + 主要上傳區(drag + click)' },
+    button: { purpose: '緊湊 Button 觸發 — form 內單欄 / 空間省(click-only)' },
   },
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — dropzone 僅 hover / drag-over 態,無按壓視覺(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-primary-subtle', 'bg-surface'],
+    bg: ['bg-surface', 'bg-disabled'],
     fg: [],
     ring: ['ring-ring'],
   },

package/src/components/FileUpload/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-upload'

package/src/components/FileViewer/can-render-image.ts

@@ -0,0 +1,15 @@
+// 2026-07-06 D3 bundle fix:canRenderImage 從 image-renderer.tsx 拆出成獨立小 module。
+// 理由:file-viewer.tsx 需要「同步」呼叫 canRenderImage(renderer registry canRender 判斷
+// + Filmstrip thumb 分流),但 image-renderer.tsx 頂層 import react-zoom-pan-pinch(~12KB gz)——
+// 靜態 import 會把整個 lib 拉進 consumer 首屏 bundle,即使 viewer 從未打開。
+// 拆出後 file-viewer.tsx 靜態 import 本檔(純 util,零依賴),ImageRenderer 本體走 React.lazy
+// 動態 import,react-zoom-pan-pinch 延後到 viewer 首次渲染 image 時才載入。
+
+const IMAGE_EXTS = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'avif', 'bmp', 'ico'])
+
+/** 判斷檔案是否可用 ImageRenderer 渲染。 */
+export function canRenderImage(file: { mimeType: string; name: string }): boolean {
+  if (file.mimeType.startsWith('image/')) return true
+  const ext = file.name.split('.').pop()?.toLowerCase()
+  return ext ? IMAGE_EXTS.has(ext) : false
+}