@qijenchen/design-system 0.1.0-beta.80 → 0.1.0-beta.82

package/src/components/Field/field.spec.md

@@ -193,7 +193,7 @@ Field render 時迭代**全部** control child 的 `type.fieldLayout`,**任一**
 
 **第一行對齊責任**:Field 的 block control area **不加 paddingTop**(避免跟 RadioGroup 自帶 `py = calc((field-height - 1lh) / 2)` double)。需 label 對齊的 block primitive 自行保證第一行位置(RadioGroup/CheckboxGroup 自帶 ✓;FileDropzone/RichTextEditor 自管)。
 
-**已宣告 block**:`RadioGroup`、`CheckboxGroup`(checkbox-group.tsx:92)。新增 `FileDropzone` 等同模式加 `fieldLayout = 'block'`。
+**已宣告 block**:`RadioGroup`、`CheckboxGroup`(checkbox-group.tsx:93)。新增 `FileDropzone` 等同模式加 `fieldLayout = 'block'`。
 
 ---
 
@@ -253,8 +253,8 @@ Field 透過 Context 暴露以下狀態給子元件（Primitive 可以透過 `us
 
 label 文字後可帶 info icon(ℹ)hover 出 tooltip 補充說明:`<FieldLabel info="說明文字">`。
 
-- **與 label 間距 `gap-1`(4px)**、InfoIcon **16px 固定**、色 `fg-muted` hover `fg-secondary`(field.tsx L388-408)
-- **disabled 時整顆不渲染**(L400)— info 是 action affordance(hover 互動),非類型身份 indicator,non-editable 隱藏
+- **與 label 間距 `gap-1`(4px)**、InfoIcon **16px 固定**、色 `fg-muted` hover `fg-secondary`(field.tsx L391-416)
+- **disabled 時整顆不渲染**(L403)— info 是 action affordance(hover 互動),非類型身份 indicator,non-editable 隱藏
 - 設計定位:inline action pattern(補充工具,視覺退後)— label 的 primary interaction 是 input,info 是輔助
 
 ---
@@ -386,16 +386,18 @@ Field 內的資料輸入控件（Input / NumberInput / DatePicker / Select / Com
 
 ## Field state machine SSOT(v13.3)
 
-**Canonical**:**focus dominates everything**(M11 延伸:focus 勝 hover/open/error-rest)。Cursor in input = user 編輯中 = 永遠藍。對齊 Material 3 / Polaris / Ant Design 5 共識。SSOT 在 `field-wrapper.tsx` 三 compoundVariant — 改一處全 control + cell + 各 variant 跟動(**例外:error state CSS 目前逐 control 實作**——input.tsx / select.tsx / number-input.tsx 各自帶 `border-error` 系列,不在 field-wrapper compoundVariants,改 error 需逐 control 同步)。 <!-- @benchmark-unverified -->
+**Canonical**(2026-07-04 Q1 拍板修訂):**focus dominates everything — 除 error**。無 error 時 cursor in input = 藍;**有 error 時聚焦維持紅**(error 勝 focus 的「顏色」通道;修錯中不可失去 error 訊號)。開始編輯 → edit-clears-error(`useFormValidation`)→ 自然回 focus 藍。Benchmark 實查:MUI(error+focused 紅框加粗,OutlinedInput.js error rule 排 focused 後)/ Ant 5(`activeBorderColor: colorError` 紅框紅 glow,input/style/variants.ts)/ Polaris(紅 border 聚焦持續 + 獨立藍 outline,TextField.module.css)三家聚焦時 error 紅皆保留;唯一切藍的 Carbon 靠 in-field 紅 icon 補償(DS 無此通道故不採)。SSOT 全在 `field-wrapper.tsx` compoundVariants(**含 error** — 2026-07-04 起 `error` 為 cva 變體,原逐 control `border-error` 系列已 retire,控件只傳 `error` flag)。
 
 | State | Token | CSS |
 |---|---|---|
 | rest | `--border` | `border-border` |
 | hover(無 focus)| `--border-hover` | `hover:border-border-hover` |
-| **focus** | `--primary` | **`focus-within:!border-primary`**(`!important` 勝 data-state)|
+| **focus(無 error)** | `--primary` | **`focus-within:!border-primary`**(error:false compound;`!important` 勝 data-state)|
 | focus + hover | `--primary` | `focus-within:hover:!border-primary`(M11 AND case)|
 | open(無 focus)| `--border-hover` | `data-[state=open]:border-border-hover` |
-| error | `--error` | `focus-within:border-error focus-within:hover:border-error` |
+| **error(edit 全程,含聚焦)** | `--error` | `border-error hover:border-error-hover focus-within:!border-error focus-within:hover:!border-error`(error:true compound)|
+
+**Error × focus 疊加 canonical(2026-07-05 user 拍板「照 Mantine」)**:錯誤欄位聚焦時**視覺完全不變**(紅框同色同寬,無加深/加粗/ring/暈)。依據:DS 聚焦主機制 =「邊框換 primary 基準色、無第二訊號」,12 家實查中唯一同款機制的 Mantine(Input.module.css:focus 僅 border 換 primary-filled、outline none)在此題同樣選擇不變;保紅又加訊號的三家(MUI 粗 / Ant 暈 / Bootstrap 暈)前提是其一般聚焦本來就有該第二訊號可染紅,DS 無此前提。**已知代價(documented tradeoff,非 bug)**:無游標的觸發器(Select / DatePicker / TimePicker)error 聚焦時無視覺聚焦指示(文字框靠游標);Mantine 同款弱點。未來若升級全 DS 聚焦語言(一般態加第二訊號),本題應同步重議(錯誤態染紅該訊號,對齊 MUI/Ant/Bootstrap 結構)。D4 finding「error+focus 零 focus delta」據此結案為 user-拍板 intentional。
 
 副作用(自動達成 Ant「選後藍 / 取消灰」):選 option → Radix `onCloseAutoFocus` return focus → focus-within fires → 藍 / 點外取消 → focus 移外 → 灰。純 focus 機制無需 transient class。
 
@@ -414,7 +416,7 @@ Field 內的資料輸入控件（Input / NumberInput / DatePicker / Select / Com
 | **L1 Slot** | `patterns/element-anatomy/item-anatomy.tsx` | `<ItemPrefix>` / `<ItemSuffix>`(永遠 `h-[1lh]` 對齊第 1 行) |
 | **L2 Align** | `field-wrapper.tsx` `nakedCellRowModeAlign` | host cell `data-row-mode` propagate(autoRow→items-start / fixed→items-center)|
 | **L3 State machine** | **繼承 Field default v13.3**(↑ 上方 SSOT)| 不重定義 |
-| **L4 Display hover** | `field-wrapper.tsx` `nakedCellEditableDisplayHover` | editable cell display mode `outline-1 outline-offset:-1 outline-[var(--border-hover)]`(cell wrapper outline)。**v15.13 design intent(user-accepted 2026-05-07)**:hover ring 蓋 cell.borderRight。**known asymmetry**(2026-05-09 user 重抓):只 **right** 邊 outline 跟 cell own border-r 同位置覆蓋成 1 條;top/left/bottom 邊 outline 在 cell.outer 內 1px,grid lines(前 row border-b / 前 cell border-r / row 自己 border-b 在 cell.outer 外 1px)露出 → 視覺 4 邊不對稱。**Pending design decision**(等 user 拍板才 ship):4 邊都蓋(spec 1 selection-style)vs 4 邊都不蓋(spec 2 inset 1px)vs 維持現狀。三層 SSOT:state source = cell wrapper / paint owner = 混合(hover=cell / edit=Field)/ grid divider = DataTable own |
+| **L4 Display hover** | `field-wrapper.tsx` `nakedCellEditableDisplayHover` | editable cell display mode `outline-1 outline-offset:-1 outline-[var(--cell-hover-outline-color,var(--border-hover))]`(cell wrapper outline;2026-05-10 Slice D:spreadsheet overlay 啟用時 DataTable cell host 可 set `--cell-hover-outline-color: transparent` 抑制 outline、讓 overlay layer 接管 hover ring paint,fallback 即 `--border-hover` 既有行為不變)。**v15.13 design intent(user-accepted 2026-05-07)**:hover ring 蓋 cell.borderRight。**known asymmetry**(2026-05-09 user 重抓):只 **right** 邊 outline 跟 cell own border-r 同位置覆蓋成 1 條;top/left/bottom 邊 outline 在 cell.outer 內 1px,grid lines(前 row border-b / 前 cell border-r / row 自己 border-b 在 cell.outer 外 1px)露出 → 視覺 4 邊不對稱。**Pending design decision**(等 user 拍板才 ship):4 邊都蓋(spec 1 selection-style)vs 4 邊都不蓋(spec 2 inset 1px)vs 維持現狀。三層 SSOT:state source = cell wrapper / paint owner = 混合(hover=cell / edit=Field)/ grid divider = DataTable own |
 | **L5 Position(v14,2026-05-06 revert v12)** | naked compoundVariant flow | Field 留 layout flow,**不**用 `!absolute`(v12 absolute 跟 autoRowHeight 不相容)。視覺接受 cell `border-r grid` + Field border 2px 雙線;cell border-r divider 永遠保留(對齊 L4 Invariant divider-owner / editor-owner 分離)|
 | **L6 Cell trigger indicator(v15,2026-05-09)** | naked-display branch + `showDisplayEndIcon?: boolean` opt-in | DataTable cell-registry 顯式傳 `showDisplayEndIcon` → Field component 內部 `<ItemSuffix>` 渲對應 trigger icon(Select/Combobox/PeoplePicker → ChevronDown / DatePicker → CalendarIcon / TimePicker → Clock / LinkInput 例外無 suffix)。table 外用法不傳此 prop = 純展示無 icon。詳 `.claude/planning/cell-indicator-ssot-rfc.md`。|
 

package/src/components/Field/field.tsx

@@ -527,7 +527,8 @@ export const fieldMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'active' 移除 — field-wrapper compoundVariants 無按壓態(TimePicker 2026-07-04 audit 同結論)(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: [],
     fg: ['text-error-text', 'text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],

package/src/components/Field/form-validation.spec.md

@@ -41,9 +41,11 @@
 ### Submit 驗證
 
 7. **Submit 驗證全部**——點擊 submit 時對所有欄位執行驗證(不依賴個別 field 的 blur 狀態)
-8. **Anchor 到第一個錯誤**——若有任何欄位出錯,scroll 並 focus 到第一個錯誤欄位。多次 submit 重試時,每次都重新驗證全部欄位並重新計算「第一個錯誤」(rule 7 的自然結果),不保持上次 anchor 位置
+8. **Anchor 到第一個錯誤**——若有任何欄位出錯,scroll 並 focus 到第一個錯誤欄位(**「第一個」= DOM 視覺順序**,非 validate key 宣告順序;對齊瀏覽器原生 reportValidity + react-hook-form shouldFocusError,2026-07-07 code 同步)。多次 submit 重試時,每次都重新驗證全部欄位並重新計算「第一個錯誤」(rule 7 的自然結果),不保持上次 anchor 位置
 9. **Async / cross-field 驗證 defer 到 submit**——某些驗證無法在 blur 當下完成(如「名稱是否重複」需要 API 查詢、跨欄位邏輯如「結束日不得早於開始日」),這些在 submit 時統一判斷。若有錯誤,同樣 anchor 到第一個出錯欄位。
 
+**Double-submit 防護(2026-07-05 D4 codify,規則 9 的必然配套)**:async onSubmit 進行期間,重複 submit(連點按鈕 / 連按 Enter)一律忽略——否則業務層被並發呼叫兩次(重複建立資源的經典事故)。submit 期間狀態以 `isSubmitting` 暴露(餵 Button loading / disabled;`submitDisabled` 同步為 true);onSubmit 拋錯時先復位 `isSubmitting` 再讓錯誤原樣上拋(不吞錯,表單回到可重送狀態)。對齊 react-hook-form `formState.isSubmitting` / Polaris / Mantine form submitting 內建。 <!-- @benchmark-unverified -->
+
 ### 驗證分層
 
 | 層級 | 負責者 | 時機 | 範例 |
@@ -81,6 +83,7 @@ const form = useFormValidation({
 | Blur validation timing(1/2/6)+ Edit 清 error(5)+ Escape 回復(4) | **`useFormValidation` 內建(不可配置)** |
 | Submit 全驗 + anchor 第一個錯誤(7/8)+ 業務/async 錯誤同軌(9) | **`useFormValidation.handleSubmit` 內建** |
 | Dirty tracking + Submit button 狀態(Create/Update) | **`useFormValidation.submitDisabled`** |
+| Double-submit 防護 + submit 進行中狀態(規則 9 配套) | **`useFormValidation.handleSubmit` 重入 guard + `isSubmitting`** |
 | Field error visual(紅框 + FieldError) | Field 元件 `invalid` context(既有,hook 不侵入) |
 
 **v1 邊界**(誠實 documented):(a) `getInputProps` 支援 value/onChange 型控件(Input / Textarea / NumberInput / Select / Combobox / DatePicker / TimePicker;onChange 收 event 或裸值皆可);Checkbox / Switch(onCheckedChange)用 `setFieldValue` 自接。(b) focus-first-error 以 DOM `name` 屬性定位 —— native input 生效;非 native 控件 focus 略過(error 視覺仍由 Field 紅框 + FieldError 呈現)。(c) 不用 hook 的 consumer 仍可全手動(Field `invalid` prop 是 engine-agnostic 的,見 field.spec.md 定位)。
@@ -147,10 +150,10 @@ Email 格式 / URL 格式 / 必填等「single-field 純 syntax」blur 即可判
 
 Form validation 的 ARIA / 鍵盤行為(對齊 WCAG 3.3.1 Error Identification + 3.3.3 Error Suggestion):
 
-- **Error message ARIA**:Field error 容器 `id="field-{name}-error"`,Input 設 `aria-describedby="field-{name}-error"` + `aria-invalid="true"`;SR 在 focus field 時自動讀「{label}, {error message}」
+- **Error message ARIA**:`<FieldError>` 容器 id = `{fieldId}-error`(fieldId 為 Field 的 `id` prop / `useId`,field.tsx:174),控件經 Field context 自動接 `aria-errormessage`(有 error 時指向 errorId)+ `aria-invalid="true"`;`aria-describedby` 保留給 FieldDescription(descriptionId)。SR 在 focus field 時可得 label + error 完整資訊;接線 SSOT 見 `field.spec.md`「驗證與 aria 屬性」段(input.tsx:187-190)
 - **Submit error scroll**:submit 失敗後,focus 自動 jump 到第一個 invalid field(`field.focus()` + `scrollIntoView({block: 'center'})`);對齊 Material / Atlassian 慣例 <!-- @benchmark-unverified -->
 - **Error live region**:跨欄位 / async error 用 `aria-live="polite"` 容器宣告 — SR 在空閒時讀出,不中斷使用者打字
-- **Required indicator**:label 的 `*` 為純視覺、對讀屏隱藏(`aria-hidden="true"`,field.tsx:392);required 語意由內部輸入控件的 `aria-required`(input.tsx:192)承擔,避免讀屏讀出「asterisk」語義不清
+- **Required indicator**:label 的 `*` 為純視覺、對讀屏隱藏(`aria-hidden="true"`,field.tsx:395);required 語意由內部輸入控件的 `aria-required`(input.tsx:188)承擔,避免讀屏讀出「asterisk」語義不清
 - **Color-only error 警告**:error border 紅色之外必有文字訊息(WCAG 1.4.1 不僅靠顏色)— 由 `<FieldError>` 文字承擔;DS **不**在 input 內放 error 狀態 icon(見 `field-controls.spec.md`「禁止事項」)
 
 ## 相關

package/src/components/Field/use-form-validation.ts

@@ -27,6 +27,8 @@
  * 8 Anchor 到第一個錯誤    → focus + scrollIntoView({block:'center'});每次 submit 重算
  * 9 Async / 跨欄位 defer 到 submit → onSubmit 回傳 field-keyed errors → 同 8 anchor
  * + Submit button:Create 永遠 enabled / Update disabled-until-dirty → `submitDisabled`
+ * + Double-submit 防護(2026-07-05 D4):await onSubmit 期間重入直接忽略;`isSubmitting`
+ *   暴露餵 Button loading / disabled;onSubmit reject 先復位再原樣上拋(不吞錯)
  *
  * ── v1 邊界(spec「可執行層」段 documented)──
  * - getInputProps 支援 value/onChange 型控件(Input / Textarea / NumberInput / Select /
@@ -77,8 +79,10 @@ export interface UseFormValidationReturn<T extends FieldValues> {
   errors: Partial<Record<keyof T, string>>
   /** 任一欄位偏離 initialValues(深比對,還原回原值 = false) */
   isDirty: boolean
-  /** Submit button disabled 狀態(intent 驅動,見 options.intent) */
+  /** Submit button disabled 狀態(intent 驅動,見 options.intent;submit 進行中一併 disabled) */
   submitDisabled: boolean
+  /** Submit 進行中(await onSubmit 期間 true)— 餵 Button loading;double-submit 防護的 state 面 */
+  isSubmitting: boolean
   /** Spread 到 value/onChange 型控件:`<Input {...form.getInputProps('name')} />` */
   getInputProps: <K extends keyof T & string>(name: K) => FormFieldInputProps<T[K]>
   /** 接 `<form onSubmit={form.handleSubmit}>`(規則 7/8/9) */
@@ -108,16 +112,21 @@ function extractValue(eventOrValue: unknown): unknown {
 /** 規則 8:focus + scroll 到第一個錯誤欄位。以 DOM name 屬性定位(native input);
  *  找不到(非 native 控件)→ 靜默略過,error 視覺仍由 Field 紅框呈現。 */
 function focusFirstError(errorNames: string[]) {
-  for (const name of errorNames) {
-    const el = document.getElementsByName(name)[0] as HTMLElement | undefined
-    if (el) {
-      el.focus()
-      el.scrollIntoView({ block: 'center', behavior: 'smooth' })
-      return
-    }
+  // 2026-07-07 修(deep-audit A.1b 殘項):「第一個錯誤」以 DOM 順序為準(= 使用者看到的視覺第一),
+  // 非 validate key 宣告順序 — spec 規則 8 自然語意;對齊瀏覽器原生 reportValidity(DOM 序 focus
+  // 首個 invalid)+ react-hook-form shouldFocusError。
+  const els = errorNames
+    .map((name) => document.getElementsByName(name)[0] as HTMLElement | undefined)
+    .filter((el): el is HTMLElement => Boolean(el))
+    .sort((a, b) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1))
+  const el = els[0]
+  if (el) {
+    el.focus()
+    el.scrollIntoView({ block: 'center', behavior: 'smooth' })
   }
 }
 
+// code-quality-allow: long-function — 單一 validation 生命週期 state machine(blur 驗證/edit 清 error/Escape 回復/submit 聚焦首錯)拆散會把耦合狀態跨函式傳遞,降低可讀性;對齊 react-hook-form useForm 本體同級長度
 export function useFormValidation<T extends FieldValues>(
   options: UseFormValidationOptions<T>,
 ): UseFormValidationReturn<T> {
@@ -185,10 +194,18 @@ export function useFormValidation<T extends FieldValues>(
     [form, validateField],
   )
 
+  // 2026-07-05 D4 double-submit 防護:連點 submit / 連按 Enter 在 await onSubmit(規則 9
+  // async 業務驗證)期間會並發呼叫 onSubmit(重複建立資源的經典事故)。ref 同步擋重入
+  // (state 有 render 延遲,擋不住同 tick 連點);state 暴露 isSubmitting 餵 Button
+  // loading / disabled。對齊 RHF formState.isSubmitting / Polaris / Mantine form submitting。
+  const isSubmittingRef = React.useRef(false)
+  const [isSubmitting, setIsSubmitting] = React.useState(false)
+
   /** 規則 7/8/9:submit 全驗 + anchor 第一個錯誤 + 業務錯誤同軌 */
   const handleSubmit = React.useCallback(
     async (e?: React.FormEvent) => {
       e?.preventDefault()
+      if (isSubmittingRef.current) return // double-submit guard(見上方 comment)
       const current = form.getValues()
       // 規則 7:對所有 validate keys 全跑(不依賴個別 blur 狀態);每次 submit 重算(規則 8)
       const formatErrors: string[] = []
@@ -210,18 +227,27 @@ export function useFormValidation<T extends FieldValues>(
         return
       }
       // 規則 9:業務 / async / 跨欄位驗證 defer 到 submit(onSubmit 回傳 field-keyed errors)
-      const businessErrors = await onSubmit(current)
-      if (businessErrors && typeof businessErrors === 'object') {
-        const names = Object.keys(businessErrors).filter(
-          (k) => businessErrors[k as keyof T] != null,
-        )
-        for (const name of names) {
-          form.setError(name as Path<T>, {
-            type: 'business',
-            message: businessErrors[name as keyof T] as string,
-          })
+      // try/finally(2026-07-05 D4):onSubmit reject 先復位 isSubmitting 再讓 rejection 原樣
+      // 上拋(不吞錯,對齊 RHF handleSubmit re-throw canonical)— 表單回到可重送狀態而非卡死。
+      isSubmittingRef.current = true
+      setIsSubmitting(true)
+      try {
+        const businessErrors = await onSubmit(current)
+        if (businessErrors && typeof businessErrors === 'object') {
+          const names = Object.keys(businessErrors).filter(
+            (k) => businessErrors[k as keyof T] != null,
+          )
+          for (const name of names) {
+            form.setError(name as Path<T>, {
+              type: 'business',
+              message: businessErrors[name as keyof T] as string,
+            })
+          }
+          if (names.length > 0) focusFirstError(names)
         }
-        if (names.length > 0) focusFirstError(names)
+      } finally {
+        isSubmittingRef.current = false
+        setIsSubmitting(false)
       }
     },
     [form, validate, onSubmit],
@@ -231,8 +257,10 @@ export function useFormValidation<T extends FieldValues>(
     values,
     errors,
     isDirty,
-    // Submit Button 狀態 canonical:Create 永遠 enabled / Update disabled-until-dirty
-    submitDisabled: intent === 'update' ? !isDirty : false,
+    // Submit Button 狀態 canonical:Create 永遠 enabled / Update disabled-until-dirty;
+    // submit 進行中一律 disabled(double-submit 防護的 UI 面,2026-07-05 D4)
+    submitDisabled: (intent === 'update' ? !isDirty : false) || isSubmitting,
+    isSubmitting,
     getInputProps,
     handleSubmit,
     reset: () => form.reset(),

package/src/components/FieldControlGroup/field-control-group.anatomy.stories.tsx

@@ -1,8 +1,9 @@
-// @story-trait-rationale: Inspector + ColorMatrix N/A — FieldControlGroup 是
+// @anatomy-rationale: Inspector + ColorMatrix N/A — FieldControlGroup 是
 // self-contained layout-primitive(border-collapse 接合 N 個 Field child),
 // spec frontmatter `variants: {}` / `sizes: {}` / `traits: []`(明示 layout-primitive 無 trait variants)。
 // 無 cva color variant → ColorMatrix N/A;無 interactive prop control(僅 children layout)→ Inspector N/A。
-// 對齊 design-system-audit Dim 13 trait-rationale 例外 SSOT。
+// 對齊 design-system-audit Dim 13 `@anatomy-rationale` 例外 marker(audit-prompts.md Dim 13;
+// 2026-07-04 修:原誤用 @story-trait-rationale — 那是 R3 trait escape,Dim 13 機械檢查認不得)。
 import type { Meta, StoryObj } from '@storybook/react'
 import { FieldControlGroup } from './field-control-group'
 import { Select } from '@/design-system/components/Select/select'
@@ -43,8 +44,8 @@ export const Overview: Story = {
       <section>
         <h3 className="text-body font-bold mb-2">範例</h3>
         <FieldControlGroup block>
-          <Select className="w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
-          <Select className="w-[100px]" options={OPS} value="contains" onChange={() => {}} aria-label="篩選運算子" />
+          <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+          <Select className="!w-[100px]" options={OPS} value="contains" onChange={() => {}} aria-label="篩選運算子" />
           <Input className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
         </FieldControlGroup>
       </section>
@@ -61,7 +62,7 @@ export const SizeMatrix: Story = {
         <div key={size}>
           <p className="text-caption text-fg-muted mb-2">size="{size}"</p>
           <FieldControlGroup block>
-            <Select size={size} className="w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+            <Select size={size} className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
             <Input size={size} className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
           </FieldControlGroup>
         </div>
@@ -78,21 +79,21 @@ export const StateBehavior: Story = {
       <div>
         <p className="text-caption text-fg-muted mb-2">default</p>
         <FieldControlGroup block>
-          <Select className="w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+          <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
           <Input className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
         </FieldControlGroup>
       </div>
       <div>
         <p className="text-caption text-fg-muted mb-2">disabled(整 group children 各自 disabled)</p>
         <FieldControlGroup block>
-          <Select className="w-[120px]" options={FIELDS} value="name" onChange={() => {}} disabled aria-label="篩選欄位" />
+          <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} disabled aria-label="篩選欄位" />
           <Input className="flex-1" defaultValue="無線滑鼠" disabled aria-label="篩選值" />
         </FieldControlGroup>
       </div>
       <div>
         <p className="text-caption text-fg-muted mb-2">cell error(其中一 child invalid → border-error;聚焦該 child 時才提升到 z-3 蓋過鄰接 border)</p>
         <FieldControlGroup block>
-          <Select className="w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+          <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
           <Input className="flex-1" defaultValue="無線滑鼠" error aria-label="篩選值" />
         </FieldControlGroup>
       </div>
@@ -109,8 +110,8 @@ export const Accessibility: Story = {
         Container 不加 ARIA role(透明 wrapper);children 各自 aria-label。Tab 鍵在 children 之間正常移動,no focus trap。
       </p>
       <FieldControlGroup block>
-        <Select className="w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
-        <Select className="w-[100px]" options={OPS} value="contains" onChange={() => {}} aria-label="篩選運算子" />
+        <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+        <Select className="!w-[100px]" options={OPS} value="contains" onChange={() => {}} aria-label="篩選運算子" />
         <Input className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
       </FieldControlGroup>
     </div>

package/src/components/FieldControlGroup/field-control-group.principles.stories.tsx

@@ -101,7 +101,7 @@ export const UsageGuidance: Story = {
         <Field>
           <FieldLabel>聯絡電話</FieldLabel>
           <FieldControlGroup block>
-            <Select className="w-[88px]" options={CODES} value="+886" onChange={() => {}} />
+            <Select className="!w-[88px]" options={CODES} value="+886" onChange={() => {}} />
             <Input className="flex-1" placeholder="912 345 678" />
           </FieldControlGroup>
         </Field>
@@ -111,8 +111,8 @@ export const UsageGuidance: Story = {
       <section>
         <h2 className="text-body-lg font-bold mb-3">Mode B — Filter row 場景</h2>
         <FieldControlGroup block>
-          <Select className="w-[140px]" options={FIELDS} value="name" onChange={() => {}} />
-          <Select className="w-[120px]" options={OPS} value="contains" onChange={() => {}} />
+          <Select className="!w-[140px]" options={FIELDS} value="name" onChange={() => {}} />
+          <Select className="!w-[120px]" options={OPS} value="contains" onChange={() => {}} />
           <Input className="flex-1" defaultValue="無線滑鼠" />
         </FieldControlGroup>
       </section>

package/src/components/FieldControlGroup/field-control-group.spec.md

@@ -79,7 +79,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 ## Width 配置 canonical(W-A,對齊 Ant)
 
 **子 controls 自管 width**:
-- Fixed:`<Select className="w-[140px]">`
+- Fixed:`<Select className="!w-[140px]">`
 - Flex:`<Input className="flex-1">`
 - 混合 OK(filter row 典型:fixed + fixed + flex)
 
@@ -94,7 +94,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 <Field size="lg">
   <FieldLabel>電話</FieldLabel>
   <FieldControlGroup>  {/* 各 child 自動繼承外層 Field context size */}
-    <Select className="w-[80px]" options={codes} />
+    <Select className="!w-[80px]" options={codes} />
     <Input className="flex-1" />
   </FieldControlGroup>
 </Field>
@@ -103,7 +103,7 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 **Mode B**(standalone):**逐一給每個 child 設 `size`**(設 `<FieldControlGroup size>` 無效)。
 ```tsx
 <FieldControlGroup>
-  <Select size="md" className="w-[120px]" options={fields} />
+  <Select size="md" className="!w-[120px]" options={fields} />
   <Input size="md" className="flex-1" />
 </FieldControlGroup>
 ```

package/src/components/FieldControlGroup/field-control-group.tsx

@@ -39,8 +39,8 @@ import type { FieldSize } from '@/design-system/components/Field/field-context'
  * ```tsx
  * // Filter row: 2 fixed select + 1 flex value
  * <FieldControlGroup>
- *   <Select className="w-[140px]" options={fields} />
- *   <Select className="w-[120px]" options={ops} />
+ *   <Select className="!w-[140px]" options={fields} />
+ *   <Select className="!w-[120px]" options={ops} />
  *   <Input className="flex-1" placeholder="輸入值..." />
  * </FieldControlGroup>
  *
@@ -48,7 +48,7 @@ import type { FieldSize } from '@/design-system/components/Field/field-context'
  * <Field>
  *   <FieldLabel>電話</FieldLabel>
  *   <FieldControlGroup>
- *     <Select className="w-[80px]" options={codes} />
+ *     <Select className="!w-[80px]" options={codes} />
  *     <Input className="flex-1" />
  *   </FieldControlGroup>
  * </Field>

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

@@ -46,8 +46,9 @@ export const Overview: Story = {
               {[
                 ['name', 'string', '必填', '檔名'],
                 ['mode', "'compact' | 'rich'", "'compact'", 'compact=Paperclip 16px icon / rich=Avatar 48px 縮圖'],
+                ['surface', "'form' | 'upload-manager'", "'form'", '所在容器 context:form=rich 為 border card / upload-manager=rich 無邊框無 bg(面板自身是容器,avatar 作 item 邊界)+ padding 縮減。詳 spec「邊框 / 背景」「Padding」表'],
                 ['status', "'uploading' | 'completed' | 'error'", '—', '上傳狀態(不傳=已上傳靜態)'],
-                ['progress', 'number', '—', '上傳進度 0-100(有 status 時顯示 bar;completed 強制 100%)'],
+                ['progress', 'number', '0', '上傳進度 0-100(有 status 時顯示 bar;completed 強制 100%)'],
                 ['description', 'ReactNode', '—', 'rich 任意場景 / compact 只有 error 才顯示。ReactNode — 可含 inline clickable link(如「View log」)'],
                 ['thumbnailSrc', 'string', '—', 'rich mode 的縮圖 URL(圖片類檔案)'],
                 ['actions', 'ReactNode', '—', 'suffix actions(例:delete / cancel button)'],
@@ -101,7 +102,7 @@ export const ColorMatrix: Story = {
         <H3>Status × 元素 色彩矩陣</H3>
         <Desc>
           FileItem 本身無色彩變體——text 走 item-anatomy row primitive 共用 token
-          (`--foreground` / `--fg-secondary`);background 依 mode 固定(rich = `--surface` + border / compact 無 status = `--secondary` / compact 有 status = transparent),**無 hover-bg**(見下方 Container background table)。
+          (`--foreground` / `--fg-secondary`);background 依 mode × surface 決定(rich + surface=form = `--surface` + border / rich + surface=upload-manager = 無邊框無 bg / compact 無 status = `--secondary` / compact 有 status = transparent),**無 hover-bg**(見下方 Container background table)。
           Status 才驅動色彩:progress bar 色(inProgress / success / error)+ status icon 色(check / X)+ description 色(error 時升階)。
         </Desc>
         <div className="overflow-x-auto mb-4">
@@ -152,7 +153,7 @@ export const ColorMatrix: Story = {
       <div>
         <H3>Container background(per mode,**無 hover-bg**)</H3>
         <Desc>
-          FileItem 設計準則(2026-04-23):**永不顯示 hover-bg**。三種型態皆已 permanent-anchored(rich = border card / compact 無 status = bg-secondary / compact 有 status = 底部 progress bar),再加 hover-bg 是 double-emphasis 視覺雜。affordance 只靠 `cursor-pointer`(onClick 時)+ hover-swap icon fade。詳 spec「Hover 行為 canonical」。
+          FileItem 設計準則(2026-04-23):**永不顯示 hover-bg**。各型態皆已 permanent-anchored(rich + surface=form = border card / rich + surface=upload-manager = avatar 作 item 邊界 / compact 無 status = bg-secondary / compact 有 status = 底部 progress bar),再加 hover-bg 是 double-emphasis 視覺雜。affordance 只靠 `cursor-pointer`(onClick 時)+ hover-swap icon fade。詳 spec「Hover 行為 canonical」。
         </Desc>
         <div className="overflow-x-auto">
           <table className="text-caption border-collapse">
@@ -160,7 +161,8 @@ export const ColorMatrix: Story = {
               <tr><Th>Mode / State</Th><Th>Background</Th><Th>Rationale</Th></tr>
             </thead>
             <tbody>
-              <tr><Td mono>rich(all status)</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface</span> + border</span></Td><Td>永遠是 card(border + rounded + bg-surface)</Td></tr>
+              <tr><Td mono>rich + surface=form(all status)</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface</span> + border</span></Td><Td>card(border + rounded + bg-surface)——Slack / Notion attachment 慣例</Td></tr>
+              <tr><Td mono>rich + surface=upload-manager(all status)</Td><Td><span className="font-mono">無邊框無 bg(只留 rounded-md)</span></Td><Td>面板自身是容器,avatar 作 item 邊界。詳 spec「邊框 / 背景」表</Td></tr>
               <tr><Td mono>compact 無 status</Td><Td><span className="inline-flex items-center gap-1.5"><Swatch value="--secondary" size="sm" /><span className="font-mono">--secondary</span>(= neutral-3)</span></Td><Td>靜態 pill,對齊 Badge low / ProgressBar track SSOT</Td></tr>
               <tr><Td mono>compact 有 status</Td><Td><span className="font-mono">transparent</span></Td><Td>底部 progress bar 作 permanent affordance(分隔線型)</Td></tr>
               <tr><Td mono>hover(任意 mode)</Td><Td><span className="font-mono">無變化</span></Td><Td>permanent-anchored → 不加 hover-bg。cursor-pointer 作 affordance(onClick 時)</Td></tr>

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

@@ -160,7 +160,8 @@ const FileItem = React.forwardRef<HTMLDivElement, FileItemProps>(
           className={cn(
             'shrink-0 transition-opacity',
             statusConfig.color,
-            hoverAction && 'group-hover/row:opacity-0',
+            // 2026-07-05 D4:鍵盤 focus 同步觸發 swap(:has(:focus-visible),對齊 item-anatomy SUFFIX_HOVER_REVEAL_BY_GROUP SSOT)
+            hoverAction && 'group-hover/row:opacity-0 group-has-[:focus-visible]/row:opacity-0',
           )}
           aria-hidden
         />
@@ -173,7 +174,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 transition-opacity"
+            className="absolute inset-0 opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity"
           />
         )}
       </span>

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

@@ -440,7 +440,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">{"詳 `fileupload.spec.md` 「A11y 預設」段。摘要:\n\n-  role=\"button\"  +  tabIndex=0 (disabled 時  -1 )\n- Enter / Space 鍵觸發檔案選取浮窗(模擬 click)\n-  aria-disabled={true}  當 disabled\n-  <input type=\"file\">  以  hidden (display:none) 隱藏,移出無障礙樹;互動由外層  role=\"button\"  wrapper 承載,accessible name 來自 wrapper 內 Empty 的 title + description 文字"}</p>
+      <p className="whitespace-pre-line">{"詳 `file-upload.spec.md` 「A11y 預設」段。摘要:\n\n-  role=\"button\"  +  tabIndex=0 (disabled 時  -1 )\n- Enter / Space 鍵觸發檔案選取浮窗(模擬 click)\n-  aria-disabled={true}  當 disabled\n-  <input type=\"file\">  以  hidden (display:none) 隱藏,移出無障礙樹;互動由外層  role=\"button\"  wrapper 承載,accessible name 來自 wrapper 內 Empty 的 title + description 文字"}</p>
     </div>
   ),
 }

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

@@ -59,7 +59,7 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 | data-state | 情境 | 視覺 |
 |------------|------|------|
 | `idle`(預設) | 使用者未互動 | dashed `border-border`（**元件邊框 `--border`,非 `--divider` 分隔線**）+ surface 底 |
-| `hover` = `drag-over`（**統一,純 border-driven,對齊 Ant Dragger `colorPrimaryHover`**)| 游標懸停 / 拖檔進入 | **`border-primary`**（只變邊框）+ 底維持 surface（不變 bg）。state 信號靠邊框,非底色;兩態同視覺 |
+| `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` 後生效)|
 
@@ -134,6 +134,9 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 - **多檔拖放 + `multiple=false`**:只取過濾後第一個檔交給 `onUpload`,不拋錯(見「Props 行為」)
 - **空選取(0 檔)**:不觸發任何 callback;`files={[]}` 不渲染清單(等同不傳)
 - **maxSize / accept 全擋下**:`onUpload` 不觸發,只觸發 `onReject`
+- **同檔重選**(2026-07-05 D4):input value 於 dispatch 後清空 — 「上傳失敗修正後重選同檔」「刪除後重傳同檔」仍觸發 `onUpload`(瀏覽器對同路徑檔案不重發 change event,不清空則靜默無反應)
+- **拖曳滑過內部子元素**(2026-07-05 D4):pointer 移過 Empty 的 icon/title 時 drag-over 高亮不熄滅(dragleave 帶 relatedTarget guard,避免經典 drag-flicker)
+- **Disabled / loading 時拖檔 drop**(2026-07-05 D4):操作被吞掉 — 仍 `preventDefault` 擋瀏覽器預設「在當前 tab 開啟被丟檔案」的整頁導航,`onUpload` 不觸發
 - Disabled / loading 見「四狀態視覺」;dark mode / density 由 semantic token 自動處理
 
 ---

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

@@ -132,6 +132,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
@@ -178,7 +182,7 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
           // 消費 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">
@@ -226,7 +230,12 @@ 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 = ''
+            }}
           />
           <Button
             variant="tertiary"
@@ -259,20 +268,29 @@ 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)
         }}
@@ -287,9 +305,11 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
           // 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 邊框,底色維持 surface(不變 bg)。state 信號靠邊框,非底色。
-          // 2026-06-11 R2(M5 狀態疊加):hover 變 primary 僅限 idle/error —— disabled/loading 維持原邊框(spec「disabled 邊框不變色」)
-          'data-[state=idle]:hover:border-primary data-[state=drag-over]:border-primary',
+          // 兩者都 → 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',
@@ -307,7 +327,12 @@ 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
@@ -366,7 +391,8 @@ export const fileUploadMeta = {
   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-surface', 'bg-disabled'],
     fg: [],

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
+}