@qijenchen/design-system 0.1.0-beta.10

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

@@ -0,0 +1,322 @@
+// @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 * as React from 'react'
+import { Paperclip, CircleCheck, XCircle, Download, RotateCw } from 'lucide-react'
+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'
+
+/**
+ * FileItem — 檔案顯示 / 上傳進度
+ *
+ * Typography: 閱讀模式 — text-body (14px) 預設行高 (1.5)
+ *
+ * 兩種 mode（精簡 vs 完整內容呈現）:
+ *
+ * compact（★ default）: Paperclip 16px 在左。右側 content + bar。
+ *   py = gap = 4px (gap-1)，對稱。
+ *   description 只有 error 才顯示。
+ *   bar 跟文字左邊對齊（在 icon 右邊的 column 內）。
+ *
+ * rich: Avatar 48px square 在左（顯示檔案內容縮圖）。右側 content + bar。
+ *   多行 description（size / status message）。
+ *   有 bar → justify-between（bar 底部對齊 avatar）
+ *   無 bar → justify-center（文字垂直置中對齊 avatar）
+ *
+ * status 可選。不傳 = 已上傳檔案（無 bar，可點擊下載）。
+ * onClick → hover:bg-neutral-hover + cursor-pointer。
+ */
+
+const STATUS_ICON = {
+  completed: { icon: CircleCheck, color: 'text-success' },
+  error: { icon: XCircle, color: 'text-error' },
+} as const
+
+// ProgressBar status 映射:uploading=inProgress(藍) / completed=success(綠) / error=error(紅)
+// 與 ProgressBar 元件的 status prop 對齊,不需再維護 PROGRESS_COLOR 本地 map。
+const PROGRESS_STATUS_MAP = {
+  uploading: 'inProgress',
+  completed: 'success',
+  error: 'error',
+} as const
+
+const AVATAR_SIZE = 48
+const ICON_PX = 16
+
+export interface FileItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+  name: string
+  /**
+   * 兩種呈現 mode（精簡 vs 完整）：
+   * - `compact`（預設）：paperclip + filename 單行 inline
+   * - `rich`：縮圖 + 檔名 + size + status + progress 的完整 card 呈現
+   */
+  mode?: 'compact' | 'rich'
+  status?: 'uploading' | 'completed' | 'error'
+  progress?: number
+  /** rich mode: 檔案大小、狀態訊息。compact: 只有 error 才顯示。 ReactNode 支援 inline clickable link(如「View log」)。 */
+  description?: React.ReactNode
+  thumbnailSrc?: string
+  actions?: React.ReactNode
+  onClick?: () => void
+  /**
+   * Hover 動作(passive 狀態 icon 變互動 button 的 UX):
+   * - `onDownload`:有值時,`status="completed"` 的綠 ✓ icon 在 row hover 時
+   *   換成 Download ↓ button;click 觸發 onDownload。無值保持 passive 綠 ✓。
+   * - `onRetry`:有值時,`status="error"` 的紅 ✗ icon 在 row hover 時換成 RotateCw ⟲
+   *   button;click 觸發 onRetry。無值保持 passive 紅 ✗。
+   *
+   * 世界級對照:Gmail / Slack / Dropbox 附件的 passive 狀態 → hover 變 action
+   * 的 UX,使用者知道檔案狀態且能立即行動。
+   */
+  onDownload?: () => void
+  onRetry?: () => void
+}
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
+  (
+    {
+      name,
+      mode = 'compact',
+      status,
+      progress = 0,
+      description,
+      thumbnailSrc,
+      actions,
+      onClick,
+      onDownload,
+      onRetry,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const isRich = mode === 'rich'
+    const hasStatus = !!status
+    const statusConfig = status && status !== 'uploading' ? STATUS_ICON[status] : null
+    const progressWidth = status === 'completed' ? 100 : progress
+
+    // compact 只有 error 才顯示 description
+    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 是
+    // 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)。
+    // 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}
+        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]'
+
+    // 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。
+    const slotHw = 'var(--field-height-xs)'
+
+    const hoverAction =
+      status === 'completed' && onDownload ? { icon: Download, onClick: onDownload, label: '下載' } :
+      status === 'error' && onRetry        ? { icon: RotateCw, onClick: onRetry,    label: '重試' } :
+      null
+
+    const statusSlot = statusConfig ? (
+      <span
+        data-unbounded="true"
+        className="relative inline-flex items-center justify-center shrink-0"
+        style={{ width: slotHw, height: slotHw }}
+      >
+        {/* Passive 狀態 icon:預設可見;若有 hover-swap,row-hover 時淡出 */}
+        <statusConfig.icon
+          size={ICON_PX}
+          className={cn(
+            'shrink-0 transition-opacity',
+            statusConfig.color,
+            hoverAction && 'group-hover/row:opacity-0',
+          )}
+          aria-hidden
+        />
+        {/* Active action:row-hover 時淡入(rich + compact 同 Button xs 統一) */}
+        {hoverAction && (
+          <Button
+            variant="text"
+            size="xs"
+            iconOnly
+            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"
+          />
+        )}
+      </span>
+    ) : null
+
+    const suffix = (
+      <div
+        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
+          // 的 SurfaceHeader dismiss canonical(2026-04-22 v5)。
+          // **child selector `[&>[data-unbounded]]`(非 descendant)**:只針對 suffix
+          // wrapper **直接子元素**(statusSlot span、actions Button)套 margin,
+          // 避免 status slot 內部 hover-swap Button(nested)也套造成 layout 跳動。
+          '[&>[data-unbounded]]:my-[calc((1lh-var(--field-height-xs))/2)]',
+        )}
+      >
+        {status === 'uploading' && isRich && (
+          <span className="text-fg-secondary tabular-nums">{progress}%</span>
+        )}
+        {statusSlot}
+        {actions}
+      </div>
+    )
+
+    // content row — 消費 ItemContent primitive(封裝 label + desc + mt-gap token SSOT)。
+    // 兩 mode 共用:primitive 改 → 兩 mode 同步,不需 grep。
+    // typography:scanning mode(2026-04-23 user 指示)—— label body(14/1.3) + desc caption(12/1.3);
+    // row 本身加 `leading-compact` 配合 scanning idiom(同 MenuItem row)。
+    const contentRow = (
+      <div className="flex items-start gap-2">
+        <ItemContent
+          label={name}
+          description={showDesc ? description : undefined}
+          mode="scanning"
+          descriptionTone={status === 'error' ? 'error' : 'secondary'}
+        />
+        {suffix}
+      </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 按鈕負責鍵盤。
+    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' : ''
+
+    // ── rich(含縮圖完整呈現)——AR17 canonical:加邊框 + gap-2 ──
+    // Rich mode 是「檔案 card」風格,外框讓每個 row 視覺上是獨立 card
+    // (Slack / Notion / Linear attachment 慣例)
+    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',
+            hoverClass,
+            className,
+          )}
+          onClick={onClick}
+          {...rowA11y}
+          {...props}
+        >
+          <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 高
+              - `justify-between`(有 bar)/`justify-center`(無 bar):
+                * 1-line desc:label 頂 + progress bar 底 **自動對齊 avatar 頂/底**
+                * 無 bar:content 垂直 center 對齊 avatar 中
+              - `gap-2`:desc ↔ progress bar **至少 8px gap**(multi-line desc 時 bar 溢出仍保 8px)
+              - row `items-start`:avatar top-align 作視覺引導(tight-stack box 內 item 邊界) */}
+          <div
+            className={cn(
+              'flex flex-col flex-1 min-w-0 gap-2',
+              progressBar ? 'justify-between' : 'justify-center',
+            )}
+            style={{ minHeight: AVATAR_SIZE }}
+          >
+            {contentRow}
+            {progressBar}
+          </div>
+        </div>
+      )
+    }
+
+    // ── compact: py-2 對稱, bar absolute 底部 ──
+    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',
+          compactStaticBg,
+          hoverClass,
+          className,
+        )}
+        onClick={onClick}
+        {...rowA11y}
+        {...props}
+      >
+        <ItemPrefix>
+          <Paperclip size={ICON_PX} className="shrink-0 text-fg-muted" aria-hidden />
+        </ItemPrefix>
+        {/* Compact 共用 contentRow(via ItemContent primitive SSOT)—— 先前 inline
+            hand-craft 導致 compact label↔desc gap 跟 rich 不同步。shared contentRow
+            保證兩 mode 修 primitive 一處全同步。 */}
+        <div className="flex flex-col flex-1 min-w-0">
+          {contentRow}
+        </div>
+
+        {/* ProgressBar: absolute 底部, left 對齊 label(跳過 icon + gap) */}
+        {progressBar && (
+          <div className="absolute bottom-0 right-3" style={{ left: `calc(0.75rem + ${ICON_PX}px + 0.5rem)` }}>
+            {progressBar}
+          </div>
+        )}
+      </div>
+    )
+  },
+)
+FileItem.displayName = 'FileItem'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const fileItemMeta = {
+  component: 'FileItem',
+  family: 2,
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-neutral-hover', 'bg-secondary', 'bg-surface'],
+    fg: ['text-fg-muted', 'text-fg-secondary'],
+    ring: [],
+  },
+} as const
+
+export { FileItem }

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

@@ -0,0 +1,326 @@
+// @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 * as React from 'react'
+import { Upload as UploadIcon, X } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Empty } from '@/design-system/components/Empty/empty'
+import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
+import { FileItem } from '@/design-system/components/FileItem/file-item'
+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 渲染。
+ *
+ * ── 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
+ *
+ * ── children 插槽 ──
+ * 預設渲染 `<Empty icon={Upload} title description />` — 重用 Empty 元件 own
+ * 的「icon + title + description 垂直居中」SSOT 避免視覺漂移。Empty 改字體 /
+ * gap / icon 尺寸時 FileUpload 自動跟進。若 consumer 傳 children 則整個覆寫。
+ *
+ * ── API ──
+ * onUpload: 使用者選取或拖放檔案時觸發,回傳 File[](至少 1 個)。
+ * multiple: 允許多檔。預設 false(單檔)。
+ * accept:   MIME filter(例 "image/*,.pdf"),傳給 <input type=file>。
+ * maxSize:  單檔最大 bytes;超過靜默忽略(consumer 若需要錯誤提示,走 onReject)。
+ * onReject: 被 maxSize / accept 擋下的檔案(提供錯誤訊息顯示機會)。
+ */
+
+/**
+ * Uploaded / uploading file status item(for `files` prop)。
+ * Consumer 持 state(progress / status),FileUpload 只負責渲染。
+ */
+export interface FileUploadStatus {
+  id: string
+  name: string
+  /** bytes */
+  size?: number
+  /** Upload 進度(0-100)— uploading 時顯示 progress bar */
+  progress?: number
+  status?: 'uploading' | 'completed' | 'error'
+  /** Error 訊息 / size 等 description */
+  description?: React.ReactNode
+  /** Thumbnail URL for rich mode */
+  thumbnailSrc?: string
+}
+
+export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onDrop'> {
+  onUpload?: (files: File[]) => void
+  onReject?: (files: File[], reason: 'size' | 'type') => void
+  multiple?: boolean
+  accept?: string
+  maxSize?: number
+  disabled?: boolean
+  /**
+   * Loading 狀態(async 上傳 / 伺服器處理中)。
+   * - 顯示 CircularProgress 取代預設 Empty 內容
+   * - 阻擋新點擊 / drag 事件(避免 double-submit)
+   * - 宣告 `aria-busy="true"` 讓 screen reader 感知處理中
+   * - Consumer 負責在上傳完成後自己切回 `loading={false}`
+   */
+  loading?: boolean
+  /** Loading 狀態的文字標題(預設「上傳中…」) */
+  loadingTitle?: string
+  /** 標題文字(預設「Click or drag file here to upload」) */
+  title?: string
+  /** 說明文字(預設「Support for a single or bulk upload」) */
+  description?: string
+  /** 若傳入 children,覆寫預設 Empty 結構 */
+  children?: React.ReactNode
+  /**
+   * Uploaded / uploading 檔案清單。傳入 → FileUpload 在 drop zone 下方渲染列表。
+   * 不傳 → 不顯示(consumer 可自行用 FileItem 組成,pre-2026-04-24 行為)。
+   * 每項有 status 狀態會對應 icon:
+   *   - `uploading`:CircularProgress(+ progress bar 若 progress 給)
+   *   - `completed`:綠色 ✓(success 狀態視覺確認)
+   *   - `error`:紅色 ✗(+ description 顯示錯誤訊息)
+   */
+  files?: FileUploadStatus[]
+  /** File list 每項顯示模式。Default: 'compact'(單行);'rich' = 含 thumbnail / size / progress bar */
+  fileListMode?: 'compact' | 'rich'
+  /** File list 移除 callback。有值 → 每項右側顯示 X dismiss button;無 → 不可移除(view-only) */
+  onRemove?: (id: string) => void
+  /** File list dismiss button ARIA label template。預設 `移除 {name}`。For i18n. */
+  removeAriaLabel?: (name: string) => string
+}
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
+  (
+    {
+      onUpload,
+      onReject,
+      multiple = false,
+      accept,
+      maxSize,
+      disabled = false,
+      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
+      description = multiple ? 'Support for a single or bulk upload' : 'Support for a single file upload', // i18n-allow: DS default; consumer override via description prop
+      children,
+      files,
+      fileListMode = 'compact',
+      onRemove,
+      removeAriaLabel = (name: string) => `移除 ${name}`, // i18n-allow: DS default; consumer override via removeAriaLabel prop
+      className,
+      onClick,
+      ...props
+    },
+    ref,
+  ) => {
+    const inputRef = React.useRef<HTMLInputElement>(null)
+    const [isDragOver, setDragOver] = React.useState(false)
+
+    const filterAndDispatch = (files: FileList | null) => {
+      if (!files || files.length === 0) return
+      const accepted: File[] = []
+      const rejectedBySize: File[] = []
+      const rejectedByType: File[] = []
+
+      Array.from(files).forEach((f) => {
+        if (maxSize != null && f.size > maxSize) {
+          rejectedBySize.push(f)
+          return
+        }
+        if (accept && !matchAccept(f, accept)) {
+          rejectedByType.push(f)
+          return
+        }
+        accepted.push(f)
+      })
+
+      if (rejectedBySize.length) onReject?.(rejectedBySize, 'size')
+      if (rejectedByType.length) onReject?.(rejectedByType, 'type')
+      if (accepted.length) onUpload?.(multiple ? accepted : accepted.slice(0, 1))
+    }
+
+    const handleClick = (e: React.MouseEvent<HTMLDivElement>) => {
+      if (!disabled) inputRef.current?.click()
+      onClick?.(e)
+    }
+
+    // State 優先序:disabled > loading > drag-over > idle(disabled 最硬,loading 次之)
+    const state = disabled ? 'disabled' : loading ? 'loading' : isDragOver ? 'drag-over' : 'idle'
+    const isBlocked = disabled || loading
+
+    const hasFiles = Array.isArray(files) && files.length > 0
+
+    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',
+        )}
+        aria-label="Uploaded files"
+      >
+        {files!.map((f) => (
+          <li key={f.id} className="list-none">
+            <FileItem
+              mode={fileListMode}
+              name={f.name}
+              status={f.status}
+              progress={f.progress}
+              description={f.description ?? (f.size != null ? formatBytes(f.size) : undefined)}
+              thumbnailSrc={f.thumbnailSrc}
+              actions={
+                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。
+                  <Button
+                    iconOnly
+                    variant="text"
+                    size="xs"
+                    startIcon={X}
+                    aria-label={removeAriaLabel(f.name)}
+                    onClick={(e) => {
+                      e.stopPropagation()
+                      onRemove(f.id)
+                    }}
+                    className="text-fg-muted hover:text-foreground"
+                  />
+                ) : undefined
+              }
+            />
+          </li>
+        ))}
+      </ul>
+    ) : null
+
+    return (
+      <div ref={ref} className={cn('w-full', hasFiles && 'flex flex-col')}>
+      <div
+        role="button"
+        tabIndex={isBlocked ? -1 : 0}
+        aria-disabled={disabled || undefined}
+        aria-busy={loading || undefined}
+        data-state={state}
+        onClick={handleClick}
+        onKeyDown={(e) => {
+          if (isBlocked) return
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault()
+            inputRef.current?.click()
+          }
+        }}
+        onDragEnter={(e) => {
+          if (isBlocked) return
+          e.preventDefault()
+          setDragOver(true)
+        }}
+        onDragLeave={(e) => {
+          if (isBlocked) return
+          e.preventDefault()
+          setDragOver(false)
+        }}
+        onDragOver={(e) => {
+          if (isBlocked) return
+          e.preventDefault()
+        }}
+        onDrop={(e) => {
+          if (isBlocked) return
+          e.preventDefault()
+          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。
+          // 不再硬寫 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',
+          className,
+        )}
+        {...props}
+      >
+        <input
+          ref={inputRef}
+          type="file"
+          className="hidden"
+          multiple={multiple}
+          accept={accept}
+          disabled={disabled}
+          onChange={(e) => filterAndDispatch(e.target.files)}
+        />
+        {loading ? (
+          <Empty
+            icon={<CircularProgress size={48} />}
+            title={loadingTitle}
+          />
+        ) : (
+          children ?? (
+            <Empty
+              icon={UploadIcon}
+              title={title}
+              description={description}
+            />
+          )
+        )}
+      </div>
+      {fileListNode}
+      </div>
+    )
+  },
+)
+FileUpload.displayName = 'FileUpload'
+
+// ── helper: bytes formatter ───────────────────────────────────────────────
+function formatBytes(n: number): string {
+  if (n < 1024) return `${n} B`
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`
+  if (n < 1024 * 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(1)} MB`
+  return `${(n / (1024 * 1024 * 1024)).toFixed(1)} GB`
+}
+
+// ── helpers ─────────────────────────────────────────────────────────────────
+
+function matchAccept(file: File, accept: string): boolean {
+  const patterns = accept.split(',').map((s) => s.trim().toLowerCase())
+  const fileName = file.name.toLowerCase()
+  const fileType = file.type.toLowerCase()
+  return patterns.some((p) => {
+    if (p.startsWith('.')) return fileName.endsWith(p) // 副檔名 e.g. ".pdf"
+    if (p.endsWith('/*')) return fileType.startsWith(p.slice(0, -1)) // e.g. "image/*"
+    return fileType === p // 完整 MIME
+  })
+}
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const fileUploadMeta = {
+  component: 'FileUpload',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-neutral-hover', 'bg-primary-subtle', 'bg-surface'],
+    fg: [],
+    ring: ['ring-ring'],
+  },
+} as const
+
+export { FileUpload }