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

package/dist/components/Field/use-form-validation.js

@@ -0,0 +1,137 @@
+import * as React from "react";
+import { useForm } from "react-hook-form";
+function extractValue(eventOrValue) {
+  if (eventOrValue && typeof eventOrValue === "object" && "target" in eventOrValue && eventOrValue.target && typeof eventOrValue.target === "object" && "value" in eventOrValue.target) {
+    return eventOrValue.target.value;
+  }
+  return eventOrValue;
+}
+function focusFirstError(errorNames) {
+  const els = errorNames.map((name) => document.getElementsByName(name)[0]).filter((el2) => Boolean(el2)).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" });
+  }
+}
+function useFormValidation(options) {
+  const { initialValues, intent = "create", validate, onSubmit } = options;
+  const form = useForm({
+    defaultValues: initialValues,
+    mode: "onSubmit",
+    shouldFocusError: false
+    // 規則 8 自己 focus(RHF 依賴 register ref,本 hook 不走 register)
+  });
+  const values = form.watch();
+  const { errors: rhfErrors, isDirty } = form.formState;
+  const errors = React.useMemo(() => {
+    var _a;
+    const out = {};
+    for (const key of Object.keys(rhfErrors)) {
+      const msg = (_a = rhfErrors[key]) == null ? void 0 : _a.message;
+      if (msg) out[key] = msg;
+    }
+    return out;
+  }, [rhfErrors]);
+  const validateField = React.useCallback(
+    (name) => {
+      const fn = validate == null ? void 0 : validate[name];
+      if (!fn) return;
+      const current = form.getValues();
+      const message = fn(current[name], current);
+      if (message) form.setError(name, { type: "format", message });
+      else form.clearErrors(name);
+    },
+    [form, validate]
+  );
+  const getInputProps = React.useCallback(
+    (name) => {
+      const path = name;
+      return {
+        name,
+        value: form.watch(path),
+        onChange: (eventOrValue) => {
+          if (form.getFieldState(path).error) form.clearErrors(path);
+          form.setValue(path, extractValue(eventOrValue), {
+            shouldDirty: true
+          });
+        },
+        // 規則 2:blur 驗證(focus 中永不驗 = 規則 1 自然成立)
+        onBlur: () => validateField(name),
+        // 規則 4:Escape 回復原值,不觸發驗證
+        onKeyDown: (e) => {
+          if (e.key === "Escape") {
+            form.resetField(path);
+            form.clearErrors(path);
+          }
+        }
+      };
+    },
+    [form, validateField]
+  );
+  const isSubmittingRef = React.useRef(false);
+  const [isSubmitting, setIsSubmitting] = React.useState(false);
+  const handleSubmit = React.useCallback(
+    async (e) => {
+      e == null ? void 0 : e.preventDefault();
+      if (isSubmittingRef.current) return;
+      const current = form.getValues();
+      const formatErrors = [];
+      if (validate) {
+        for (const name of Object.keys(validate)) {
+          const fn = validate[name];
+          if (!fn) continue;
+          const message = fn(current[name], current);
+          if (message) {
+            form.setError(name, { type: "format", message });
+            formatErrors.push(name);
+          } else {
+            form.clearErrors(name);
+          }
+        }
+      }
+      if (formatErrors.length > 0) {
+        focusFirstError(formatErrors);
+        return;
+      }
+      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] != null
+          );
+          for (const name of names) {
+            form.setError(name, {
+              type: "business",
+              message: businessErrors[name]
+            });
+          }
+          if (names.length > 0) focusFirstError(names);
+        }
+      } finally {
+        isSubmittingRef.current = false;
+        setIsSubmitting(false);
+      }
+    },
+    [form, validate, onSubmit]
+  );
+  return {
+    values,
+    errors,
+    isDirty,
+    // 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(),
+    setFieldValue: (name, value) => form.setValue(name, value, { shouldDirty: true })
+  };
+}
+export {
+  useFormValidation
+};
+//# sourceMappingURL=use-form-validation.js.map

package/dist/components/Field/use-form-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-form-validation.js","sources":["../../../src/components/Field/use-form-validation.ts"],"sourcesContent":["/**\n * useFormValidation — form-validation.spec.md 方法論的可執行層(SSOT executable arm)\n *\n * ── 定位 ──\n * 把 `form-validation.spec.md` 的 9 條驗證方法論編成**不可配置的預設**——consumer 拿到就是\n * canonical 行為,沒有 API 可以違反(M17「SSOT 必可傳播」:方法論從 prose 變 executable)。\n *\n * ── 實作基礎 ──\n * 基於 react-hook-form(direct dependency,完全 wrapped 不外露——對齊 DS「基於 X」引擎慣例:\n * DataTable 基於 TanStack / DatePicker 基於 react-day-picker / Toast 基於 sonner)。\n * Consumer 不 install、不 import、看不到 RHF API。RHF 提供 values state / dirty 深比對 /\n * errors store / resetField;驗證「時機」由本 hook own(RHF 的 mode/reValidateMode 不外露)。\n *\n * ── 與 Field 家族的關係(engine-agnostic 分層,field.spec.md「定位」段)──\n * Field 保持純 layout + context(MUI FormControl 派,可用於 cell / view / 無引擎場景);\n * 本 hook 住 form 層,錯誤經 consumer 一行 `<Field invalid={!!form.errors.x}>` 接入——\n * Field 層零耦合。這是「A 派的自由 + B 派的 DX」混合位置。\n *\n * ── 方法論對應(form-validation.spec.md 規則 1-9)──\n * 1 Focus 中不顯示錯誤     → 驗證只在 blur / submit 跑(無 onChange 驗證路徑)\n * 2 Blur 時驗證            → getInputProps().onBlur 跑 validate[name]\n * 3 Enter 等同 blur        → form 內 Enter 觸發 submit(全驗,超集);單行控件原生行為\n * 4 Escape 取消回復原值    → getInputProps().onKeyDown Escape → resetField + 清 error\n * 5 開始編輯立即清除 error → onChange 先清 errors[name](不論新值合法與否)\n * 6 Blur 重新驗證          → 同 2(離開時重判)\n * 7 Submit 驗證全部        → handleSubmit 對所有 validate keys 全跑(不依賴 blur 狀態)\n * 8 Anchor 到第一個錯誤    → focus + scrollIntoView({block:'center'});每次 submit 重算\n * 9 Async / 跨欄位 defer 到 submit → onSubmit 回傳 field-keyed errors → 同 8 anchor\n * + Submit button:Create 永遠 enabled / Update disabled-until-dirty → `submitDisabled`\n * + Double-submit 防護(2026-07-05 D4):await onSubmit 期間重入直接忽略;`isSubmitting`\n *   暴露餵 Button loading / disabled;onSubmit reject 先復位再原樣上拋(不吞錯)\n *\n * ── v1 邊界(spec「可執行層」段 documented)──\n * - getInputProps 支援 value/onChange 型控件(Input / Textarea / NumberInput / Select /\n *   Combobox / DatePicker / TimePicker;onChange 收 event 或裸值皆可)。Checkbox / Switch\n *   (onCheckedChange)consumer 自接 setFieldValue。\n * - focus-first-error 以 DOM `name` 屬性定位(native input 生效;非 native 控件 fallback\n *   scroll 略過,errors 視覺仍由 Field 紅框 + FieldError 呈現)。\n */\nimport * as React from 'react'\nimport { useForm } from 'react-hook-form'\nimport type { FieldValues, Path, PathValue, DefaultValues } from 'react-hook-form'\n\nexport interface UseFormValidationOptions<T extends FieldValues> {\n  /** 表單初始值(Update 場景 = 現有資料;dirty 比對基準) */\n  initialValues: T\n  /**\n   * 表單意圖,驅動 submit button 狀態(form-validation.spec.md「Submit Button 狀態」):\n   * - 'create'(default):submitDisabled 永遠 false(不讓使用者猜「為什麼按不了」)\n   * - 'update':submitDisabled = !isDirty(沒改就不用存;變更還原回 pristine 即再 disabled)\n   */\n  intent?: 'create' | 'update'\n  /**\n   * 格式驗證(blur 層,規則 2):single-field 純 syntax(email 格式 / 必填 / URL)。\n   * 回傳 error 訊息字串 = 不合法;undefined = 合法。\n   * 業務 / async / 跨欄位驗證**不要**放這裡——放 onSubmit 回傳(規則 9)。\n   */\n  validate?: Partial<Record<keyof T, (value: T[keyof T], values: T) => string | undefined>>\n  /**\n   * Submit handler(格式驗證全過後呼叫)。業務驗證(名稱重複 API / 跨欄位)在此判斷,\n   * 回傳 field-keyed error object(如 `{ name: '名稱已存在' }`)→ hook 自動 setError +\n   * anchor 到第一個錯誤(規則 9);回傳 undefined = 成功。\n   */\n  onSubmit: (values: T) => void | Partial<Record<keyof T, string>> | Promise<void | Partial<Record<keyof T, string>>>\n}\n\nexport interface FormFieldInputProps<V = unknown> {\n  name: string\n  value: V\n  onChange: (eventOrValue: unknown) => void\n  onBlur: () => void\n  onKeyDown: (e: React.KeyboardEvent) => void\n}\n\nexport interface UseFormValidationReturn<T extends FieldValues> {\n  /** 當前表單值(即時) */\n  values: T\n  /** field-keyed 錯誤訊息(餵 `<Field invalid>` + `<FieldError>`) */\n  errors: Partial<Record<keyof T, string>>\n  /** 任一欄位偏離 initialValues(深比對,還原回原值 = false) */\n  isDirty: boolean\n  /** Submit button disabled 狀態(intent 驅動,見 options.intent;submit 進行中一併 disabled) */\n  submitDisabled: boolean\n  /** Submit 進行中(await onSubmit 期間 true)— 餵 Button loading;double-submit 防護的 state 面 */\n  isSubmitting: boolean\n  /** Spread 到 value/onChange 型控件:`<Input {...form.getInputProps('name')} />` */\n  getInputProps: <K extends keyof T & string>(name: K) => FormFieldInputProps<T[K]>\n  /** 接 `<form onSubmit={form.handleSubmit}>`(規則 7/8/9) */\n  handleSubmit: (e?: React.FormEvent) => Promise<void>\n  /** 整表重置回 initialValues(清 errors + dirty) */\n  reset: () => void\n  /** Escape hatch:非 value/onChange 控件(Checkbox/Switch)手動寫值 */\n  setFieldValue: (name: keyof T & string, value: unknown) => void\n}\n\n/** onChange 收 event 或裸值皆可(對齊 Mantine getInputProps idiom):\n *  native input event → e.target.value;自訂控件裸值(string / number / Date / array)→ 原樣。 */\nfunction extractValue(eventOrValue: unknown): unknown {\n  if (\n    eventOrValue &&\n    typeof eventOrValue === 'object' &&\n    'target' in eventOrValue &&\n    eventOrValue.target &&\n    typeof eventOrValue.target === 'object' &&\n    'value' in (eventOrValue.target as object)\n  ) {\n    return (eventOrValue.target as HTMLInputElement).value\n  }\n  return eventOrValue\n}\n\n/** 規則 8:focus + scroll 到第一個錯誤欄位。以 DOM name 屬性定位(native input);\n *  找不到(非 native 控件)→ 靜默略過,error 視覺仍由 Field 紅框呈現。 */\nfunction focusFirstError(errorNames: string[]) {\n  // 2026-07-07 修(deep-audit A.1b 殘項):「第一個錯誤」以 DOM 順序為準(= 使用者看到的視覺第一),\n  // 非 validate key 宣告順序 — spec 規則 8 自然語意;對齊瀏覽器原生 reportValidity(DOM 序 focus\n  // 首個 invalid)+ react-hook-form shouldFocusError。\n  const els = errorNames\n    .map((name) => document.getElementsByName(name)[0] as HTMLElement | undefined)\n    .filter((el): el is HTMLElement => Boolean(el))\n    .sort((a, b) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1))\n  const el = els[0]\n  if (el) {\n    el.focus()\n    el.scrollIntoView({ block: 'center', behavior: 'smooth' })\n  }\n}\n\n// code-quality-allow: long-function — 單一 validation 生命週期 state machine(blur 驗證/edit 清 error/Escape 回復/submit 聚焦首錯)拆散會把耦合狀態跨函式傳遞,降低可讀性;對齊 react-hook-form useForm 本體同級長度\nexport function useFormValidation<T extends FieldValues>(\n  options: UseFormValidationOptions<T>,\n): UseFormValidationReturn<T> {\n  const { initialValues, intent = 'create', validate, onSubmit } = options\n\n  // RHF 引擎(wrapped):驗證時機由本 hook own,故 RHF 自身 mode 鎖 onSubmit 且不掛 resolver\n  // (所有 setError/clearErrors 走手動,RHF 只當 state + dirty + errors store)。\n  const form = useForm<T>({\n    defaultValues: initialValues as DefaultValues<T>,\n    mode: 'onSubmit',\n    shouldFocusError: false, // 規則 8 自己 focus(RHF 依賴 register ref,本 hook 不走 register)\n  })\n\n  // 訂閱全表(表單尺度 re-render 可接受;formState.isDirty 深比對 vs defaultValues)\n  const values = form.watch()\n  const { errors: rhfErrors, isDirty } = form.formState\n\n  const errors = React.useMemo(() => {\n    const out: Partial<Record<keyof T, string>> = {}\n    for (const key of Object.keys(rhfErrors)) {\n      const msg = (rhfErrors as Record<string, { message?: string } | undefined>)[key]?.message\n      if (msg) out[key as keyof T] = msg\n    }\n    return out\n  }, [rhfErrors])\n\n  /** 規則 2/6:blur 驗證單一欄位 */\n  const validateField = React.useCallback(\n    (name: keyof T & string) => {\n      const fn = validate?.[name]\n      if (!fn) return\n      const current = form.getValues()\n      const message = fn(current[name], current)\n      if (message) form.setError(name as Path<T>, { type: 'format', message })\n      else form.clearErrors(name as Path<T>)\n    },\n    [form, validate],\n  )\n\n  const getInputProps = React.useCallback(\n    <K extends keyof T & string>(name: K): FormFieldInputProps<T[K]> => {\n      // 泛型 K 窄化到 Path<T> 需經 unknown(RHF Path 是 template-literal type,K 不直接 overlap)\n      const path = name as unknown as Path<T>\n      return {\n        name,\n        value: form.watch(path) as T[K],\n        onChange: (eventOrValue: unknown) => {\n          // 規則 5:開始編輯立即清除 error(不論新值合法與否,給修正空間)\n          if (form.getFieldState(path).error) form.clearErrors(path)\n          form.setValue(path, extractValue(eventOrValue) as PathValue<T, Path<T>>, {\n            shouldDirty: true,\n          })\n        },\n        // 規則 2:blur 驗證(focus 中永不驗 = 規則 1 自然成立)\n        onBlur: () => validateField(name),\n        // 規則 4:Escape 回復原值,不觸發驗證\n        onKeyDown: (e: React.KeyboardEvent) => {\n          if (e.key === 'Escape') {\n            form.resetField(path)\n            form.clearErrors(path)\n          }\n        },\n      }\n    },\n    [form, validateField],\n  )\n\n  // 2026-07-05 D4 double-submit 防護:連點 submit / 連按 Enter 在 await onSubmit(規則 9\n  // async 業務驗證)期間會並發呼叫 onSubmit(重複建立資源的經典事故)。ref 同步擋重入\n  // (state 有 render 延遲,擋不住同 tick 連點);state 暴露 isSubmitting 餵 Button\n  // loading / disabled。對齊 RHF formState.isSubmitting / Polaris / Mantine form submitting。\n  const isSubmittingRef = React.useRef(false)\n  const [isSubmitting, setIsSubmitting] = React.useState(false)\n\n  /** 規則 7/8/9:submit 全驗 + anchor 第一個錯誤 + 業務錯誤同軌 */\n  const handleSubmit = React.useCallback(\n    async (e?: React.FormEvent) => {\n      e?.preventDefault()\n      if (isSubmittingRef.current) return // double-submit guard(見上方 comment)\n      const current = form.getValues()\n      // 規則 7:對所有 validate keys 全跑(不依賴個別 blur 狀態);每次 submit 重算(規則 8)\n      const formatErrors: string[] = []\n      if (validate) {\n        for (const name of Object.keys(validate)) {\n          const fn = validate[name as keyof T]\n          if (!fn) continue\n          const message = fn(current[name as keyof T], current)\n          if (message) {\n            form.setError(name as Path<T>, { type: 'format', message })\n            formatErrors.push(name)\n          } else {\n            form.clearErrors(name as Path<T>)\n          }\n        }\n      }\n      if (formatErrors.length > 0) {\n        focusFirstError(formatErrors)\n        return\n      }\n      // 規則 9:業務 / async / 跨欄位驗證 defer 到 submit(onSubmit 回傳 field-keyed errors)\n      // try/finally(2026-07-05 D4):onSubmit reject 先復位 isSubmitting 再讓 rejection 原樣\n      // 上拋(不吞錯,對齊 RHF handleSubmit re-throw canonical)— 表單回到可重送狀態而非卡死。\n      isSubmittingRef.current = true\n      setIsSubmitting(true)\n      try {\n        const businessErrors = await onSubmit(current)\n        if (businessErrors && typeof businessErrors === 'object') {\n          const names = Object.keys(businessErrors).filter(\n            (k) => businessErrors[k as keyof T] != null,\n          )\n          for (const name of names) {\n            form.setError(name as Path<T>, {\n              type: 'business',\n              message: businessErrors[name as keyof T] as string,\n            })\n          }\n          if (names.length > 0) focusFirstError(names)\n        }\n      } finally {\n        isSubmittingRef.current = false\n        setIsSubmitting(false)\n      }\n    },\n    [form, validate, onSubmit],\n  )\n\n  return {\n    values,\n    errors,\n    isDirty,\n    // Submit Button 狀態 canonical:Create 永遠 enabled / Update disabled-until-dirty;\n    // submit 進行中一律 disabled(double-submit 防護的 UI 面,2026-07-05 D4)\n    submitDisabled: (intent === 'update' ? !isDirty : false) || isSubmitting,\n    isSubmitting,\n    getInputProps,\n    handleSubmit,\n    reset: () => form.reset(),\n    setFieldValue: (name, value) =>\n      form.setValue(name as Path<T>, value as PathValue<T, Path<T>>, { shouldDirty: true }),\n  }\n}\n"],"names":["el"],"mappings":"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"}

package/dist/components/FieldControlGroup/field-control-group.d.ts

@@ -1,11 +1,10 @@
 import * as React from 'react';
-import type { FieldSize } from '../../components/Field/field-context';
 /**
  * FieldControlGroup — 多個 Field controls 視覺接合成一個 input frame
  *
  * **Naming rationale**(2026-05-04):
  * - Taxonomic 一致:FieldGroup(多 Field 堆疊)/ FieldControlGroup(多 control 接合)— scope 區分
- * - Idiom 一致:ButtonGroup(多 Button 接合)同 pattern,只是 X = field control
+ * - 命名 idiom 一致:與 ButtonGroup 共享 <X>Group 命名(X = field control);但**機制不同** — ButtonGroup 是 gap 分離群組(flex gap-2),本元件才是 border-collapse 接合(負 margin 重疊 border)
  * - 不撞 RadioGroup/CheckboxGroup(那是 1-question 多 options semantic group)
  *
  * **Behavior canonical**(verified Ant compact-item.ts L21-58):
@@ -15,10 +14,10 @@ import type { FieldSize } from '../../components/Field/field-context';
  * - z-index:default 2 / hover|focus|focus-within 3 / disabled 0
  * - Container `display: inline-flex`(Ant default)/ `block` prop → `display: flex; width: 100%`
  *
- * **Size cascade**(對齊 Field family):
- * - `size` prop default = md;cascade 到 children via implicit context inheritance(children 自管 size 或繼承 useFieldContext)
- * - Mode A:整個 FieldControlGroup 包進 Field 當 control slot,size 自動從 Field context 來
- * - Mode B:standalone 用,size 由 prop 控制
+ * **Size**(FCG 不擁有 size API；不傳遞 size 給 children,無 Context Provider / 無 cloneElement;見 spec「Size」段):
+ * - children 尺寸完全由 child 自己決定;FCG 只負責 border-collapse 接合(border / radius / z-index)
+ * - Mode A:整個 FieldControlGroup 包進 Field 當 control slot,children 各自讀外層 `<Field>` 的 context size(是 Field 的 context,不是 FCG 的)
+ * - Mode B:standalone 用,逐一給每個 child 設 `size`
  *
  * **Width 配置**(Ant Space.Compact W-A canonical):
  * - 子 controls 自管 width(`className="w-[140px]"` / `style={{width:120}}` / `flex-1` etc.)
@@ -28,8 +27,8 @@ import type { FieldSize } from '../../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>
  *
@@ -37,7 +36,7 @@ import type { FieldSize } from '../../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>
@@ -50,8 +49,6 @@ import type { FieldSize } from '../../components/Field/field-context';
  * ```
  */
 export interface FieldControlGroupProps extends React.HTMLAttributes<HTMLDivElement> {
-    /** Children size cascade(Mode B);Mode A 從 Field context 來 */
-    size?: FieldSize;
     /** Block 模式:width 100% 撐滿 parent(對齊 Ant Space.Compact `block` prop) */
     block?: boolean;
 }

package/dist/components/FieldControlGroup/field-control-group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-control-group.d.ts","sourceRoot":"","sources":["../../../src/components/FieldControlGroup/field-control-group.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gDAAgD,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,MAAM,WAAW,sBAAuB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAClF,6DAA6D;IAC7D,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,QAAA,MAAM,iBAAiB,+FA0CtB,CAAA;AAQD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAaxB,CAAA;AAEV,OAAO,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"field-control-group.d.ts","sourceRoot":"","sources":["../../../src/components/FieldControlGroup/field-control-group.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,MAAM,WAAW,sBAAuB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAClF,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,QAAA,MAAM,iBAAiB,+FA0CtB,CAAA;AASD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAaxB,CAAA;AAEV,OAAO,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/components/FieldControlGroup/field-control-group.js

@@ -2,7 +2,7 @@ import { jsx } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../../lib/utils.js";
 const FieldControlGroup = React.forwardRef(
-  ({ size: _size = "md", block = false, className, children, ...props }, ref) => {
+  ({ block = false, className, children, ...props }, ref) => {
     return /* @__PURE__ */ jsx(
       "div",
       {
@@ -43,7 +43,7 @@ const fieldControlGroupMeta = {
   family: "self-contained",
   variants: {},
   sizes: {},
-  // self-contained wrapper, sizes cascade to children only
+  // self-contained wrapper;children 尺寸自管
   states: ["default", "children-hover", "children-focus", "children-disabled"],
   tokens: {
     bg: [],

package/dist/components/FieldControlGroup/field-control-group.js.map

@@ -1 +1 @@
-{"version":3,"file":"field-control-group.js","sources":["../../../src/components/FieldControlGroup/field-control-group.tsx"],"sourcesContent":["// @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.\n// ── 消費的 SSOT ──\n// - patterns/element-anatomy/element-anatomy.spec.md(Field 家族邊界)\n// - components/Field/field-wrapper.tsx(field-height token via h-field-{sm,md,lg})\n// - components/Field/field-context.ts(useFieldContext / size cascade)\n// - tokens/uiSize/uiSize.spec.md(--field-height-{sm,md,lg})\n// - 世界級對照:Ant Space.Compact compact-item.ts(verified github.com/ant-design/ant-design/blob/master/components/style/compact-item.ts)\n//   Bootstrap input-group.scss(verified github.com/twbs/bootstrap/blob/v5.3.3/scss/forms/_input-group.scss)\n//\nimport * as React from 'react'\nimport { cn } from '@/lib/utils'\nimport type { FieldSize } from '@/design-system/components/Field/field-context'\n\n/**\n * FieldControlGroup — 多個 Field controls 視覺接合成一個 input frame\n *\n * **Naming rationale**(2026-05-04):\n * - Taxonomic 一致:FieldGroup(多 Field 堆疊)/ FieldControlGroup(多 control 接合)— scope 區分\n * - Idiom 一致:ButtonGroup(多 Button 接合)同 pattern,只是 X = field control\n * - 不撞 RadioGroup/CheckboxGroup(那是 1-question 多 options semantic group)\n *\n * **Behavior canonical**(verified Ant compact-item.ts L21-58):\n * - 子 controls 保留自身 border + radius;不 strip\n * - 鄰接子用負 margin 重疊 border(Bootstrap 也用此手法 但用 z-index 確保 focus 在最上層)\n * - first child 只留左 radii / last child 只留右 radii / middle 全 0 radii\n * - z-index:default 2 / hover|focus|focus-within 3 / disabled 0\n * - Container `display: inline-flex`(Ant default)/ `block` prop → `display: flex; width: 100%`\n *\n * **Size cascade**(對齊 Field family):\n * - `size` prop default = md;cascade 到 children via implicit context inheritance(children 自管 size 或繼承 useFieldContext)\n * - Mode A:整個 FieldControlGroup 包進 Field 當 control slot,size 自動從 Field context 來\n * - Mode B:standalone 用,size 由 prop 控制\n *\n * **Width 配置**(Ant Space.Compact W-A canonical):\n * - 子 controls 自管 width(`className=\"w-[140px]\"` / `style={{width:120}}` / `flex-1` etc.)\n * - FieldControlGroup 不另開 Cell wrapper(避免 indirection,符合 Ant idiom)\n *\n * **使用範例**:\n * ```tsx\n * // Filter row: 2 fixed select + 1 flex value\n * <FieldControlGroup>\n *   <Select className=\"w-[140px]\" options={fields} />\n *   <Select className=\"w-[120px]\" options={ops} />\n *   <Input className=\"flex-1\" placeholder=\"輸入值...\" />\n * </FieldControlGroup>\n *\n * // Phone: country code + number\n * <Field>\n *   <FieldLabel>電話</FieldLabel>\n *   <FieldControlGroup>\n *     <Select className=\"w-[80px]\" options={codes} />\n *     <Input className=\"flex-1\" />\n *   </FieldControlGroup>\n * </Field>\n *\n * // Search + button\n * <FieldControlGroup>\n *   <Input className=\"flex-1\" />\n *   <Button variant=\"primary\">搜尋</Button>\n * </FieldControlGroup>\n * ```\n */\n\nexport interface FieldControlGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Children size cascade(Mode B);Mode A 從 Field context 來 */\n  size?: FieldSize\n  /** Block 模式:width 100% 撐滿 parent(對齊 Ant Space.Compact `block` prop) */\n  block?: boolean\n}\n\nconst FieldControlGroup = React.forwardRef<HTMLDivElement, FieldControlGroupProps>(\n  ({ size: _size = 'md', block = false, className, children, ...props }, ref) => {\n    return (\n      <div\n        ref={ref}\n        // ── Ant compact-item 機制(verified):\n        //   [&>*]:relative — 子套 relative 才能 z-index 生效\n        //   [&>*]:z-[2] — default z 2(Ant 同值)\n        //   [&>*+*]:-ml-px — 鄰接子 margin-left -1px 重疊 border\n        //   hover/focus/focus-within → z-3(active border 在最上層,Bootstrap 用 z-5,Ant 用 z-3 我們對齊 Ant)\n        //   first/middle/last radii:對齊 Ant compactItemBorderRadius L67-92\n        // ── Children 自管 width(W-A,Ant idiom);Group 自身僅控制 border/radius/z-index 接合機制\n        className={cn(\n          block ? 'flex w-full' : 'inline-flex',\n          'items-stretch',\n          // z-index baseline + active layer\n          '[&>*]:relative [&>*]:z-[2]',\n          '[&>*:hover]:z-[3] [&>*:focus]:z-[3] [&>*:focus-within]:z-[3]',\n          '[&>*[disabled]]:z-0 [&>*:has([disabled])]:z-0',\n          // border overlap\n          '[&>*+*]:-ml-px',\n          // border radius — 中間 0,首/尾保留外側 radii\n          '[&>*:not(:first-child):not(:last-child)]:rounded-none',\n          '[&>*:first-child:not(:last-child)]:rounded-r-none',\n          '[&>*:last-child:not(:first-child)]:rounded-l-none',\n          // K12 fix(2026-05-04 v7 — semantic token):FCG 內 disabled cell border 用 `--border-opaque`:\n          //   ✓ 保留 global `bg-disabled`(neutral-2 灰底)— disabled state 視覺主要承載\n          //   ✓ 用 SEMANTIC `--border-opaque`(視覺等同 --border 但不跟 bg compositing)\n          //   v6 直接消費 primitive `--color-neutral-5-opaque` 違反 token 4 規則「禁 primitive 色名作 utility」,\n          //   v7 升 semantic alias `--border-opaque` 在 semantic.css(其 primitive 後盾仍是 neutral-5-opaque)\n          //   → 對齊 Ant Design colorBorderSecondary solid idiom(table 外框 / row divider 用 solid,跟 input alpha border 視覺層級分)\n          //   → 解決 alpha border 在 grey bg 上 composite 略深 perception(physical 對比問題)\n          '[&>*[data-field-mode=\"disabled\"]]:border-[var(--border-opaque)]',\n          className,\n        )}\n        data-field-control-group=\"\"\n        {...props}\n      >\n        {children}\n      </div>\n    )\n  },\n)\nFieldControlGroup.displayName = 'FieldControlGroup'\n\n// Story auto-compile metadata — Phase 4 migration(2026-05-10 #12 task complete)\n// Per scripts/compile-stories.mjs --check。FieldControlGroup is self-contained\n// structural wrapper(border-collapse pattern for Field controls)。\n// **No own sizes** — size prop is cascade-only(passes through to children Field controls,\n// not own visual variants),so sizes:{} matches spec frontmatter (no sizes declared)。\nexport const fieldControlGroupMeta = {\n  component: 'FieldControlGroup',\n  family: 'self-contained',\n  variants: {},\n  sizes: {},  // self-contained wrapper, sizes cascade to children only\n  states: ['default', 'children-hover', 'children-focus', 'children-disabled'],\n  tokens: {\n    bg: [],  // structural wrapper has no own bg\n    fg: [],\n    border: ['var(--border-opaque)'],  // K12 disabled cell border\n  },\n  defaultVariant: undefined,\n  defaultSize: undefined,\n} as const\n\nexport { FieldControlGroup }\n"],"names":[],"mappings":";;;AAsEA,MAAM,oBAAoB,MAAM;AAAA,EAC9B,CAAC,EAAE,MAAM,QAAQ,MAAM,QAAQ,OAAO,WAAW,UAAU,GAAG,MAAA,GAAS,QAAQ;AAC7E,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QAQA,WAAW;AAAA,UACT,QAAQ,gBAAgB;AAAA,UACxB;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,UAQA;AAAA,UACA;AAAA,QAAA;AAAA,QAEF,4BAAyB;AAAA,QACxB,GAAG;AAAA,QAEH;AAAA,MAAA;AAAA,IAAA;AAAA,EAGP;AACF;AACA,kBAAkB,cAAc;AAOzB,MAAM,wBAAwB;AAAA,EACnC,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,UAAU,CAAA;AAAA,EACV,OAAO,CAAA;AAAA;AAAA,EACP,QAAQ,CAAC,WAAW,kBAAkB,kBAAkB,mBAAmB;AAAA,EAC3E,QAAQ;AAAA,IACN,IAAI,CAAA;AAAA;AAAA,IACJ,IAAI,CAAA;AAAA,IACJ,QAAQ,CAAC,sBAAsB;AAAA;AAAA,EAAA;AAAA,EAEjC,gBAAgB;AAAA,EAChB,aAAa;AACf;"}
+{"version":3,"file":"field-control-group.js","sources":["../../../src/components/FieldControlGroup/field-control-group.tsx"],"sourcesContent":["// @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.\n// ── 消費的 SSOT ──\n// - patterns/element-anatomy/element-anatomy.spec.md(Field 家族邊界)\n// - components/Field/field-wrapper.tsx(field-height token via h-field-{sm,md,lg})\n// - components/Field/field-context.ts(useFieldContext / size cascade)\n// - tokens/uiSize/uiSize.spec.md(--field-height-{sm,md,lg})\n// - 世界級對照:Ant Space.Compact compact-item.ts(verified github.com/ant-design/ant-design/blob/master/components/style/compact-item.ts)\n//   Bootstrap input-group.scss(verified github.com/twbs/bootstrap/blob/v5.3.3/scss/forms/_input-group.scss)\n//\nimport * as React from 'react'\nimport { cn } from '@/lib/utils'\n\n/**\n * FieldControlGroup — 多個 Field controls 視覺接合成一個 input frame\n *\n * **Naming rationale**(2026-05-04):\n * - Taxonomic 一致:FieldGroup(多 Field 堆疊)/ FieldControlGroup(多 control 接合)— scope 區分\n * - 命名 idiom 一致:與 ButtonGroup 共享 <X>Group 命名(X = field control);但**機制不同** — ButtonGroup 是 gap 分離群組(flex gap-2),本元件才是 border-collapse 接合(負 margin 重疊 border)\n * - 不撞 RadioGroup/CheckboxGroup(那是 1-question 多 options semantic group)\n *\n * **Behavior canonical**(verified Ant compact-item.ts L21-58):\n * - 子 controls 保留自身 border + radius;不 strip\n * - 鄰接子用負 margin 重疊 border(Bootstrap 也用此手法 但用 z-index 確保 focus 在最上層)\n * - first child 只留左 radii / last child 只留右 radii / middle 全 0 radii\n * - z-index:default 2 / hover|focus|focus-within 3 / disabled 0\n * - Container `display: inline-flex`(Ant default)/ `block` prop → `display: flex; width: 100%`\n *\n * **Size**(FCG 不擁有 size API；不傳遞 size 給 children,無 Context Provider / 無 cloneElement;見 spec「Size」段):\n * - children 尺寸完全由 child 自己決定;FCG 只負責 border-collapse 接合(border / radius / z-index)\n * - Mode A:整個 FieldControlGroup 包進 Field 當 control slot,children 各自讀外層 `<Field>` 的 context size(是 Field 的 context,不是 FCG 的)\n * - Mode B:standalone 用,逐一給每個 child 設 `size`\n *\n * **Width 配置**(Ant Space.Compact W-A canonical):\n * - 子 controls 自管 width(`className=\"w-[140px]\"` / `style={{width:120}}` / `flex-1` etc.)\n * - FieldControlGroup 不另開 Cell wrapper(避免 indirection,符合 Ant idiom)\n *\n * **使用範例**:\n * ```tsx\n * // Filter row: 2 fixed select + 1 flex value\n * <FieldControlGroup>\n *   <Select className=\"!w-[140px]\" options={fields} />\n *   <Select className=\"!w-[120px]\" options={ops} />\n *   <Input className=\"flex-1\" placeholder=\"輸入值...\" />\n * </FieldControlGroup>\n *\n * // Phone: country code + number\n * <Field>\n *   <FieldLabel>電話</FieldLabel>\n *   <FieldControlGroup>\n *     <Select className=\"!w-[80px]\" options={codes} />\n *     <Input className=\"flex-1\" />\n *   </FieldControlGroup>\n * </Field>\n *\n * // Search + button\n * <FieldControlGroup>\n *   <Input className=\"flex-1\" />\n *   <Button variant=\"primary\">搜尋</Button>\n * </FieldControlGroup>\n * ```\n */\n\nexport interface FieldControlGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Block 模式:width 100% 撐滿 parent(對齊 Ant Space.Compact `block` prop) */\n  block?: boolean\n}\n\nconst FieldControlGroup = React.forwardRef<HTMLDivElement, FieldControlGroupProps>(\n  ({ block = false, className, children, ...props }, ref) => {\n    return (\n      <div\n        ref={ref}\n        // ── Ant compact-item 機制(verified):\n        //   [&>*]:relative — 子套 relative 才能 z-index 生效\n        //   [&>*]:z-[2] — default z 2(Ant 同值)\n        //   [&>*+*]:-ml-px — 鄰接子 margin-left -1px 重疊 border\n        //   hover/focus/focus-within → z-3(active border 在最上層,Bootstrap 用 z-5,Ant 用 z-3 我們對齊 Ant)\n        //   first/middle/last radii:對齊 Ant compactItemBorderRadius L67-92\n        // ── Children 自管 width(W-A,Ant idiom);Group 自身僅控制 border/radius/z-index 接合機制\n        className={cn(\n          block ? 'flex w-full' : 'inline-flex',\n          'items-stretch',\n          // z-index baseline + active layer\n          '[&>*]:relative [&>*]:z-[2]',\n          '[&>*:hover]:z-[3] [&>*:focus]:z-[3] [&>*:focus-within]:z-[3]',\n          '[&>*[disabled]]:z-0 [&>*:has([disabled])]:z-0',\n          // border overlap\n          '[&>*+*]:-ml-px',\n          // border radius — 中間 0,首/尾保留外側 radii\n          '[&>*:not(:first-child):not(:last-child)]:rounded-none',\n          '[&>*:first-child:not(:last-child)]:rounded-r-none',\n          '[&>*:last-child:not(:first-child)]:rounded-l-none',\n          // K12 fix(2026-05-04 v7 — semantic token):FCG 內 disabled cell border 用 `--border-opaque`:\n          //   ✓ 保留 global `bg-disabled`(neutral-2 灰底)— disabled state 視覺主要承載\n          //   ✓ 用 SEMANTIC `--border-opaque`(視覺等同 --border 但不跟 bg compositing)\n          //   v6 直接消費 primitive `--color-neutral-5-opaque` 違反 token 4 規則「禁 primitive 色名作 utility」,\n          //   v7 升 semantic alias `--border-opaque` 在 semantic.css(其 primitive 後盾仍是 neutral-5-opaque)\n          //   → 對齊 Ant Design colorBorderSecondary solid idiom(table 外框 / row divider 用 solid,跟 input alpha border 視覺層級分)\n          //   → 解決 alpha border 在 grey bg 上 composite 略深 perception(physical 對比問題)\n          '[&>*[data-field-mode=\"disabled\"]]:border-[var(--border-opaque)]',\n          className,\n        )}\n        data-field-control-group=\"\"\n        {...props}\n      >\n        {children}\n      </div>\n    )\n  },\n)\nFieldControlGroup.displayName = 'FieldControlGroup'\n\n// Story auto-compile metadata — Phase 4 migration(2026-05-10 #12 task complete)\n// Per scripts/compile-stories.mjs --check。FieldControlGroup is self-contained\n// structural wrapper(border-collapse pattern for Field controls)。\n// **No own sizes** — 不暴露 size prop(不傳遞給 children,無 Context Provider /\n// 無 cloneElement;children 尺寸自管,見上方 docblock「Size」段),\n// so sizes:{} matches spec frontmatter (no sizes declared)。\nexport const fieldControlGroupMeta = {\n  component: 'FieldControlGroup',\n  family: 'self-contained',\n  variants: {},\n  sizes: {},  // self-contained wrapper;children 尺寸自管\n  states: ['default', 'children-hover', 'children-focus', 'children-disabled'],\n  tokens: {\n    bg: [],  // structural wrapper has no own bg\n    fg: [],\n    border: ['var(--border-opaque)'],  // K12 disabled cell border\n  },\n  defaultVariant: undefined,\n  defaultSize: undefined,\n} as const\n\nexport { FieldControlGroup }\n"],"names":[],"mappings":";;;AAmEA,MAAM,oBAAoB,MAAM;AAAA,EAC9B,CAAC,EAAE,QAAQ,OAAO,WAAW,UAAU,GAAG,MAAA,GAAS,QAAQ;AACzD,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QAQA,WAAW;AAAA,UACT,QAAQ,gBAAgB;AAAA,UACxB;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,UAQA;AAAA,UACA;AAAA,QAAA;AAAA,QAEF,4BAAyB;AAAA,QACxB,GAAG;AAAA,QAEH;AAAA,MAAA;AAAA,IAAA;AAAA,EAGP;AACF;AACA,kBAAkB,cAAc;AAQzB,MAAM,wBAAwB;AAAA,EACnC,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,UAAU,CAAA;AAAA,EACV,OAAO,CAAA;AAAA;AAAA,EACP,QAAQ,CAAC,WAAW,kBAAkB,kBAAkB,mBAAmB;AAAA,EAC3E,QAAQ;AAAA,IACN,IAAI,CAAA;AAAA;AAAA,IACJ,IAAI,CAAA;AAAA,IACJ,QAAQ,CAAC,sBAAsB;AAAA;AAAA,EAAA;AAAA,EAEjC,gBAAgB;AAAA,EAChB,aAAa;AACf;"}

package/dist/components/FieldControlGroup/index.d.ts

@@ -0,0 +1,2 @@
+export * from './field-control-group';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/FieldControlGroup/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/FieldControlGroup/index.ts"],"names":[],"mappings":"AAIA,cAAc,uBAAuB,CAAA"}

package/dist/components/FieldControlGroup/index.js

@@ -0,0 +1,6 @@
+import { FieldControlGroup, fieldControlGroupMeta } from "./field-control-group.js";
+export {
+  FieldControlGroup,
+  fieldControlGroupMeta
+};
+//# sourceMappingURL=index.js.map

package/dist/components/FieldControlGroup/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/components/FileItem/file-item.d.ts

@@ -7,6 +7,16 @@ export interface FileItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
      * - `rich`：縮圖 + 檔名 + size + status + progress 的完整 card 呈現
      */
     mode?: 'compact' | 'rich';
+    /**
+     * 清單所在的 surface context（2026-06-03 codify rich-borderless）：
+     * - `form`（預設）：rich = border card（自立輪廓，Slack/Notion/Linear attachment 慣例）
+     * - `upload-manager`：rich = **無邊框**（Google Drive/Dropbox 上傳管理面板 —— 面板自身已是容器，
+     *   card border 多餘 = 雙層容器）；avatar 作每筆 item 視覺邊界。compact 的進度條/灰底不受 surface 影響
+     *   （由 status 決定）。
+     * surface-driven（非 status-driven）：避免 form 內 rich 上傳中變無邊框、存好變 card 的邊框閃爍。
+     * 列間 gap 由 List wrapper canonical 決定（form rich 8px / upload-manager rich 12px tight / compact 4px，見 spec）。
+     */
+    surface?: 'form' | 'upload-manager';
     status?: 'uploading' | 'completed' | 'error';
     progress?: number;
     /** rich mode: 檔案大小、狀態訊息。compact: 只有 error 才顯示。 ReactNode 支援 inline clickable link(如「View log」)。 */
@@ -14,6 +24,8 @@ export interface FileItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     thumbnailSrc?: string;
     actions?: React.ReactNode;
     onClick?: () => void;
+    /** 整列 primary action 的 accessible name；預設 `開啟 {name}`。 */
+    actionAriaLabel?: string;
     /**
      * Hover 動作(passive 狀態 icon 變互動 button 的 UX):
      * - `onDownload`:有值時,`status="completed"` 的綠 ✓ icon 在 row hover 時
@@ -33,9 +45,9 @@ export declare const fileItemMeta: {
     readonly family: 2;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default"];
     readonly tokens: {
-        readonly bg: readonly ["bg-neutral-hover", "bg-secondary", "bg-surface"];
+        readonly bg: readonly ["bg-secondary", "bg-surface"];
         readonly fg: readonly ["text-fg-muted", "text-fg-secondary"];
         readonly ring: readonly [];
     };

package/dist/components/FileItem/file-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-item.d.ts","sourceRoot":"","sources":["../../../src/components/FileItem/file-item.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AA6C9B,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IACxF,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAA;IACzB,MAAM,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,OAAO,CAAA;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mGAAmG;IACnG,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CACrB;AAGD,QAAA,MAAM,QAAQ,sFA+Nb,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}
+{"version":3,"file":"file-item.d.ts","sourceRoot":"","sources":["../../../src/components/FileItem/file-item.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AA6C9B,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IACxF,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,MAAM,CAAA;IACzB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAA;IACnC,MAAM,CAAC,EAAE,WAAW,GAAG,WAAW,GAAG,OAAO,CAAA;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mGAAmG;IACnG,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CACrB;AAGD,QAAA,MAAM,QAAQ,sFAiQb,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;CAef,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/components/FileItem/file-item.js

@@ -5,7 +5,7 @@ import { cn } from "../../lib/utils.js";
 import { Avatar } from "../Avatar/avatar.js";
 import { Button } from "../Button/button.js";
 import { ProgressBar } from "../ProgressBar/progress-bar.js";
-import { ItemPrefix, ItemContent } from "../../patterns/element-anatomy/item-anatomy.js";
+import { ItemSuffix, ItemPrefix, ItemContent } from "../../patterns/element-anatomy/item-anatomy.js";
 const STATUS_ICON = {
   completed: { icon: CircleCheck, color: "text-success" },
   error: { icon: XCircle, color: "text-error" }
@@ -21,12 +21,14 @@ const FileItem = React.forwardRef(
   ({
     name,
     mode = "compact",
+    surface = "form",
     status,
     progress = 0,
     description,
     thumbnailSrc,
     actions,
     onClick,
+    actionAriaLabel = `開啟 ${name}`,
     onDownload,
     onRetry,
     className,
@@ -43,13 +45,12 @@ const FileItem = React.forwardRef(
       {
         value: progressWidth,
         status: PROGRESS_STATUS_MAP[status],
-        height: isRich ? void 0 : 2,
+        className: isRich ? void 0 : "!h-0.5",
         "aria-label": `${name} 上傳進度`
       }
     ) : null;
-    const suffixAlign = "h-[1lh]";
     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 hoverAction = status === "completed" && onDownload ? { icon: Download, onClick: onDownload, label: `下載 ${name}` } : status === "error" && onRetry ? { icon: RotateCw, onClick: onRetry, label: `重試 ${name}` } : null;
     const statusSlot = statusConfig ? /* @__PURE__ */ jsxs(
       "span",
       {
@@ -62,9 +63,10 @@ const FileItem = React.forwardRef(
             {
               size: ICON_PX,
               className: cn(
-                "shrink-0 transition-opacity",
+                "shrink-0 transition-opacity motion-reduce:duration-0",
                 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": true
             }
@@ -81,18 +83,16 @@ const FileItem = React.forwardRef(
                 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 motion-reduce:duration-0"
             }
           )
         ]
       }
     ) : null;
     const suffix = /* @__PURE__ */ jsxs(
-      "div",
+      ItemSuffix,
       {
         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
@@ -126,14 +126,31 @@ const FileItem = React.forwardRef(
     ] });
     const rowA11y = {};
     const compactStaticBg = !progressBar ? "bg-secondary" : "";
+    const keyboardPrimaryAction = onClick ? /* @__PURE__ */ jsx(
+      "button",
+      {
+        type: "button",
+        "aria-label": actionAriaLabel,
+        className: "absolute inset-0 opacity-0 pointer-events-none",
+        onClick: (event) => {
+          event.stopPropagation();
+          onClick();
+        }
+      }
+    ) : null;
     if (isRich) {
       return /* @__PURE__ */ jsxs(
         "div",
         {
           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",
+            "group/row relative flex items-start gap-2 w-full text-body leading-compact transition-colors",
+            "has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring",
+            // surface=form → border card(自立輪廓);surface=upload-manager → 無邊框(box 自身是容器,
+            // avatar 作 item 邊界)。2026-06-03 codify rich-borderless(原僅 spec 旁註,consumer 自己移除)。
+            // 2026-06-03 圖五:upload-manager rich 拿掉 px+py(卡片移除後 py 多餘,列高靠 avatar 48 的 content minHeight;
+            // 容器 + gap 控制間距)。form 保留 px-3 py-3 卡片內距。
+            surface === "upload-manager" ? "rounded-md" : "px-3 py-3 border border-divider rounded-md bg-surface",
             hoverClass,
             className
           ),
@@ -141,6 +158,7 @@ const FileItem = React.forwardRef(
           ...rowA11y,
           ...props,
           children: [
+            keyboardPrimaryAction,
             /* @__PURE__ */ jsx(Avatar, { src: thumbnailSrc, alt: name, size: AVATAR_SIZE, shape: "square", className: "shrink-0" }),
             /* @__PURE__ */ jsxs(
               "div",
@@ -160,23 +178,34 @@ const FileItem = React.forwardRef(
         }
       );
     }
+    const compactPadX = surface === "upload-manager" ? 0 : 12;
     return /* @__PURE__ */ jsxs(
       "div",
       {
         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",
+          "group/row relative flex items-start gap-2 py-2 w-full text-body leading-compact transition-colors rounded-md",
           compactStaticBg,
+          "has-[:focus-visible]:ring-2 has-[:focus-visible]:ring-ring",
           hoverClass,
           className
         ),
+        style: { paddingInline: compactPadX },
         onClick,
         ...rowA11y,
         ...props,
         children: [
+          keyboardPrimaryAction,
           /* @__PURE__ */ jsx(ItemPrefix, { children: /* @__PURE__ */ jsx(Paperclip, { size: ICON_PX, className: "shrink-0 text-fg-muted", "aria-hidden": true }) }),
           /* @__PURE__ */ jsx("div", { className: "flex flex-col flex-1 min-w-0", children: contentRow }),
-          progressBar && /* @__PURE__ */ jsx("div", { className: "absolute bottom-0 right-3", style: { left: `calc(0.75rem + ${ICON_PX}px + 0.5rem)` }, children: progressBar })
+          progressBar && /* @__PURE__ */ jsx(
+            "div",
+            {
+              className: "absolute bottom-0",
+              style: { left: `calc(${compactPadX}px + ${ICON_PX}px + 0.5rem)`, right: compactPadX },
+              children: progressBar
+            }
+          )
         ]
       }
     );
@@ -188,9 +217,9 @@ const fileItemMeta = {
   family: 2,
   variants: {},
   sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  states: ["default"],
   tokens: {
-    bg: ["bg-neutral-hover", "bg-secondary", "bg-surface"],
+    bg: ["bg-secondary", "bg-surface"],
     fg: ["text-fg-muted", "text-fg-secondary"],
     ring: []
   }