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

package/src/components/Field/field.tsx

@@ -1,5 +1,6 @@
 // code-quality-allow: file-size — foundational composite(Field + FieldLabel + FieldDescription + FieldError + context + 8 layout variants),拆檔會讓 Field 家族互相 import 循環
 import * as React from 'react'
+import { cva } from 'class-variance-authority'
 import { Info as InfoIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { Tooltip, TooltipTrigger, TooltipContent } from '@/design-system/components/Tooltip/tooltip'
@@ -102,6 +103,20 @@ function detectControlLayout(controlNodes: React.ReactNode[]): FieldControlLayou
   return 'inline'
 }
 
+/**
+ * 偵測 control child 的偏好尺寸——control primitive 在自己的檔案掛 static `fieldPreferredSize`
+ * (如 InlineEdit = 'sm',view 態無邊框,md 過大會讓版面鬆散),Field 未顯式指定 size 時收此偏好。
+ * 對齊 detectControlLayout 讀 `type.fieldLayout` 的機制(first-declared-wins);全部缺宣告 → null。
+ */
+function detectPreferredSize(controlNodes: React.ReactNode[]): FieldSize | null {
+  for (const node of controlNodes) {
+    if (!React.isValidElement(node)) continue
+    const pref = (node.type as { fieldPreferredSize?: FieldSize } | null | undefined)?.fieldPreferredSize
+    if (pref) return pref
+  }
+  return null
+}
+
 // ── Field ───────────────────────────────────────────────────────────────────
 
 export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'id'> {
@@ -110,7 +125,8 @@ export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
   /**
    * 視覺外殼(2026-05-05)。
    * - `default`(預設)— 含 border + bg(一般 form input)
-   * - `bare` — 透明 variant,hover/focus reveal(cell-as-input substrate;VS Code/Figma toolbar idiom)
+   * - `naked` — cell-as-input(@internal;不在公開 FieldVariant 型別 — 2026-07-14 收窄至 FieldVariantInternal;2026-07-09 `bare` 退役)。edit×naked 自畫 border-based state
+   *   machine(rest/hover/focus/error);view×naked 用 transparent border,host cell 提供視覺邊框
    *
    * 透傳機制:Field 一次宣告,所有 child Field control 自動繼承(per-control prop override 可覆寫)。
    */
@@ -128,8 +144,8 @@ export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
   /**
    * Control area 佈局模型(逃生艙)。
    *
-   * 預設由 Field 自動偵測——讀第一個 control child 的 `type.fieldLayout` static 屬性,
-   * primitive 沒宣告時視為 `'inline'`。
+   * 預設由 Field 自動偵測——迭代全部 control child 的 `type.fieldLayout` static 屬性,
+   * 任一宣告為 `'block'` 即整個 area 切 block(first-block-wins);全部缺宣告時視為 `'inline'`。
    *
    * 只有兩種情況需要手動指定:
    * 1. consumer 把自己手寫的 JSX(`<div>` / 函式元件)當 control,系統無法偵測——強制 `'block'`
@@ -154,7 +170,7 @@ const Field = React.forwardRef<HTMLDivElement, FieldProps>(
       mode = 'edit',
       variant = 'default',
       orientation = 'vertical',
-      size = 'md',
+      size: sizeProp,
       required = false,
       disabled: disabledProp = false,
       invalid = false,
@@ -198,6 +214,19 @@ const Field = React.forwardRef<HTMLDivElement, FieldProps>(
     const controlLayout: FieldControlLayout =
       controlLayoutProp ?? detectControlLayout(controlNodes)
 
+    // 解析 size：consumer 顯式 > control primitive 偏好(如 InlineEdit='sm')> 預設 md
+    //   (對齊 controlLayout 三層優先序;InlineEdit 進 Field 不指定 size 時自動收 sm)
+    // 靜態偵測只看得到直接子元件;包 wrapper / memo / HOC 時由 control 於掛載時註冊補位,
+    // 讓 Field 的控件槽高度也跟上(control 自身尺寸走 useResolvedFieldSize 同步解析)。
+    const [registeredSize, setRegisteredSize] = React.useState<FieldSize | null>(null)
+    const registerPreferredSize = React.useCallback((preferred: FieldSize) => {
+      setRegisteredSize((current) => (current === preferred ? current : preferred))
+    }, [])
+    const detectedSize = detectPreferredSize(controlNodes)
+    const resolvedPreferredSize = sizeProp ?? detectedSize ?? registeredSize
+    const size: FieldSize = resolvedPreferredSize ?? 'md'
+    const sizeExplicit = resolvedPreferredSize != null
+
     const contextValue = React.useMemo<FieldContextValue>(
       () => ({
         id,
@@ -210,11 +239,13 @@ const Field = React.forwardRef<HTMLDivElement, FieldProps>(
         required,
         invalid,
         size,
+        sizeExplicit,
+        registerPreferredSize,
         orientation,
         controlLayout,
         hasFieldWrapper: true,
       }),
-      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, orientation, controlLayout]
+      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, sizeExplicit, registerPreferredSize, orientation, controlLayout]
     )
 
     // Control area：兩種佈局模型,「第一行內容中線」都錨在 field-height/2,
@@ -223,9 +254,9 @@ const Field = React.forwardRef<HTMLDivElement, FieldProps>(
     // - inline: min-h-field-{size} + items-center
     //   單行 control(Input、Button 等)中線置中於 min-h box。
     //
-    // - block:  flex-col + items-start + padding-top: calc((field-height - 1lh) / 2)
-    //   多行 control(RadioGroup 等),第一行往下推到 field-height 中線,
-    //   後續 item 自然往下流。不設 min-h(內容自己決定高度)。
+    // - block:  flex-col + items-start(不設 min-h、不加 padding-top,內容自己決定高度)
+    //   多行 control(RadioGroup 等),第一行中線由 block primitive 自帶 py 推到
+    //   field-height/2,後續 item 自然往下流。
     // Block control area 不加額外 paddingTop——block primitive(RadioGroup 等)
     // 的子元件(SelectionItem)已自帶 py = calc((field-height - 1lh) / 2),
     // 第一個 item 的文字自然落在 field-height/2。額外加 paddingTop 會 double padding。
@@ -383,6 +414,9 @@ const FieldLabel = React.forwardRef<HTMLLabelElement, FieldLabelProps>(
         style={{ ...horizontalBlockStyle, ...style }}
         data-field-slot="label"
         data-field-disabled={disabled ? '' : undefined}
+        // 2026-06-10 a11y:styled-disabled label 必明告 inactive(WCAG 1.4.3 inactive-UI 豁免需可機判;
+        // axe 對無 aria-disabled 的 fg-disabled 文字誤報 color-contrast — deep-audit 抓 8 筆)
+        aria-disabled={disabled || undefined}
         {...props}
       >
         <span className="inline-flex items-center gap-1">
@@ -403,7 +437,8 @@ const FieldLabel = React.forwardRef<HTMLLabelElement, FieldLabelProps>(
                 <button
                   type="button"
                   aria-label={info}
-                  className="inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer"
+                  // 弱化 icon hover 一階(inline-action.spec.md「Icon 色彩」;2026-07-30 前全 DS 唯一合規處)
+                  className="inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer focus-visible:outline-2 focus-visible:outline-ring"
                 >
                   <InfoIcon size={16} aria-hidden />
                 </button>
@@ -492,9 +527,22 @@ export interface FieldGroupProps extends React.HTMLAttributes<HTMLDivElement> {
   horizontalLabelWidth?: string
 }
 
+// gap variant 收進 cva(className-only 差異 → cva,per ui-development.md「cva 適用」);值仍走 Tailwind gap utility。
+const fieldGroupVariants = cva('flex flex-col min-w-0', {
+  variants: {
+    gap: {
+      compact: 'gap-3',
+      normal: 'gap-4',
+      loose: 'gap-6',
+    },
+  },
+  defaultVariants: {
+    gap: 'normal',
+  },
+})
+
 const FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(
   ({ className, gap = 'normal', horizontalLabelWidth, ...props }, ref) => {
-    const gapClass = gap === 'compact' ? 'gap-3' : gap === 'loose' ? 'gap-6' : 'gap-4'
     const groupCtxValue = React.useMemo(
       () => ({ horizontalLabelWidth }),
       [horizontalLabelWidth],
@@ -503,7 +551,7 @@ const FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(
       <FieldGroupContext.Provider value={groupCtxValue}>
         <div
           ref={ref}
-          className={cn('flex flex-col min-w-0', gapClass, className)}
+          className={cn(fieldGroupVariants({ gap }), className)}
           data-field-group=""
           {...props}
         />
@@ -524,7 +572,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'],
@@ -533,3 +582,7 @@ export const fieldMeta = {
 } as const
 
 export { Field, FieldLabel, FieldDescription, FieldError, FieldGroup }
+
+// form-validation.spec.md 可執行層(per-component index gen 只 re-export 主檔,故經此公開)
+export { useFormValidation } from './use-form-validation'
+export type { UseFormValidationOptions, UseFormValidationReturn, FormFieldInputProps } from './use-form-validation'

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

@@ -1,12 +1,9 @@
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Form Validation 設計原則
 
-> **本 spec = 跨表單的 validation 方法論 rules,非 UI 元件 spec,不適用 Layout Family 分類**(Dim 16 豁免)。
+> **本 spec = 跨表單的 validation 方法論 rules**(表單層級行為規範,適用於所有含 Field 元件的表單)。非 UI 元件 spec,不適用 Layout Family 分類(Dim 16 豁免)。
 > 元件級 validation 視覺規格住在 `Field/field.spec.md`(Field wrapper chrome)+ 各 form control spec。
 
-表單層級的驗證行為規範。適用於所有包含 Field 元件的表單。
-
 ---
 
 ## 表單驗證原則
@@ -43,9 +40,11 @@
 ### Submit 驗證
 
 7. **Submit 驗證全部**——點擊 submit 時對所有欄位執行驗證(不依賴個別 field 的 blur 狀態)
-8. **Anchor 到第一個錯誤**——若有任何欄位出錯,scroll 並 focus 到第一個錯誤欄位
+8. **Anchor 到第一個錯誤**——若有任何欄位出錯,scroll 並 focus 到第一個錯誤欄位(focus 僅對可由 DOM `name` 定位的 native input 生效,非 native 控件(Select / Combobox / RadioGroup 等)fallback 為 scroll + error 視覺,見下方「v1 邊界」(b);**「第一個」= 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` 再讓錯誤原樣上拋(不吞錯,表單回到可重送狀態)。`isSubmitting` 是這段生命週期的唯一 state owner。
+
 ### 驗證分層
 
 | 層級 | 負責者 | 時機 | 範例 |
@@ -55,16 +54,38 @@
 
 兩者都透過 `error` prop / Field context 的 `invalid` 呈現,視覺上一致(紅框 + error message)。
 
-### 可程式化的部分
-
-| 功能 | 實作位置 | 方式 |
-|---|---|---|
-| Blur validation timing | Form library config(如 RHF `mode: 'onBlur'`) | 應用層 |
-| Error clearing on edit | Form library config(`reValidateMode: 'onBlur'`）+ Field `onChange` clear | 應用層 |
-| Dirty tracking(submit button 狀態) | Form library(`isDirty`)或自訂 `useFormDirty` | 應用層 |
-| Scroll to first error | Form library(`scrollToFirstError`)或自訂 `focusFirstError` | 應用層 |
-| Field error visual | Field 元件的 `error` prop / `invalid` context | **元件層(已有)** |
-| Submit button disabled | `<Button disabled={!isDirty}>` | 應用層 consumer |
+### 可執行層:`useFormValidation`(2026-07-03,本 spec 的 executable arm)
+
+上表 9 條方法論已編成 **`useFormValidation` hook 的不可配置預設**(`Field/use-form-validation.ts`,public export)——consumer 拿到就是 canonical 行為,**沒有 API 可以違反**(M17「SSOT 必可傳播」:方法論從 prose 變 executable)。
+
+**實作基礎**:基於 react-hook-form(direct dependency,**完全 wrapped 不外露** —— consumer 不 install、不 import、看不到 RHF API;同 DataTable 基於 TanStack / DatePicker 基於 react-day-picker / Toast 基於 sonner 的 engine-wrapper 邊界)。RHF 提供 state / dirty 深比對 / errors store;驗證**時機**由本 hook own(RHF 的 mode / reValidateMode 不外露 = 不可配錯)。Consumer 只依賴 DS form contract，不依賴底層 engine API。
+
+```tsx
+const form = useFormValidation({
+  initialValues: { name: '', email: '' },
+  intent: 'update',                         // 'create'(default)| 'update' → submitDisabled 規則
+  validate: { email: (v) => !v.includes('@') ? 'Email 格式不正確' : undefined },  // 格式層(blur)
+  onSubmit: async (values) => {             // 業務層(submit);回傳 field-keyed errors = 規則 9
+    if (await nameTaken(values.name)) return { name: '名稱已存在' }
+  },
+})
+<Field invalid={!!form.errors.name}>        {/* Field 層零耦合:一行接 context */}
+  <FieldLabel>名稱</FieldLabel>
+  <Input {...form.getInputProps('name')} />
+  <FieldError>{form.errors.name}</FieldError>
+</Field>
+<Button type="submit" disabled={form.submitDisabled}>儲存</Button>
+```
+
+| 功能(規則) | 實作位置 |
+|---|---|
+| 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 定位)。
 
 ---
 
@@ -91,29 +112,29 @@
 
 四個關鍵決策,各自有世界級先例支撐:
 
-**(1) Blur-only validation(non-onChange)— 對齊 Polaris / Carbon「don't validate while typing」** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**(1) Blur-only validation(non-onChange)**
 
 Ant Design default `validateTrigger=['onChange', 'onBlur']` 對使用者 aggressive — 才打「user@」就跳「invalid email」碎念,reader 思路被打斷。Polaris / Carbon / iOS / Atlassian 共識 onBlur + submit,讓使用者「先表達完意圖再評斷」。
 
-捨棄 onChange 即時驗證的代價是「打錯看不到反饋」(打到第 3 位才發現密碼太短),但 Field 內可選 `realtime` mode 提供 hint(非 error)補足,本 spec 規範 default 行為。
+捨棄 onChange 即時驗證的代價是「打錯看不到反饋」(打到第 3 位才發現密碼太短)——本 spec 規範 default 行為(blur + submit);DS 目前無 onChange hint API。
 
-**(2) Edit 清 error + blur 重驗(已出錯後),非 onChange 重驗 — 對齊 Carbon / Atlassian 兩階段哲學** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**(2) Edit 清 error + blur 重驗(已出錯後),非 onChange 重驗**
 
 Material/Polaris/Ant 已出錯後 onChange re-validate(改第 1 字 error 又跳回)— 給使用者壓力。Carbon / Atlassian「edit 清 + blur 重驗」哲學:給使用者完整修正空間,離開時才再判決。
 
 對應使用者心智:「修改」是過程,「離開 field」是動作完成的 boundary,在 boundary 評斷比每字評斷尊重 user agency。
 
-**(3) Create always-enabled / Update disabled-until-dirty 不對稱 — 對齊 Stripe / Notion / Linear 現代慣例** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**(3) Create always-enabled / Update disabled-until-dirty 不對稱**
 
 Ant 對「Create」也 disabled-until-dirty(填了所有 required 才亮)— 但這讓使用者第一次進 form 看到 disabled button 困惑「為什麼按不了」。Stripe / Notion / Material 共識:Create 永遠 enabled — 點擊後若 invalid,顯示 error 並 scroll,使用者明確知道為什麼。
 
-Update 場景反向:沒改的 Update 沒提交意義(對齊「intent 才 commit」),disabled 表達「等你做動作」比 enabled 後點擊判斷「沒變化」更直接。對齊 Notion 設定頁 / Figma file rename 慣例。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Update 場景反向:沒改的 Update 沒提交意義(「intent 才 commit」),disabled 表達「等你做動作」比 enabled 後點擊才判斷「沒變化」更直接。
 
-**(4) 格式驗證 vs 業務驗證分層(blur vs submit)— 對齊 Material/Carbon「local vs cross-cutting validation」哲學** <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**(4) 格式驗證 vs 業務驗證分層(blur vs submit)**
 
 Email 格式 / URL 格式 / 必填等「single-field 純 syntax」blur 即可判斷;名稱重複(API 查)/ 結束日 ≥ 開始日(跨欄位)等「business / async」必須 submit 才能判 — 強行 blur 觸發 API 對使用者體驗差(每換 field 一次 API call)。
 
-對齊 Material `<TextField error>` + Form layer error 分層 / Carbon「format vs business」雙軌。視覺一致(都紅框 + error message)避免 reader 區分「為什麼這個 error 是 blur 出來那個是 submit 出來」。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+兩類 error 共用紅框 + error message 視覺，使用者不需先辨認錯誤是 blur 還是 submit 產生；差異只在驗證 ownership 與觸發時機。
 
 ## 禁止事項
 
@@ -128,25 +149,30 @@ 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}」
-- **Submit error scroll**:submit 失敗後,focus 自動 jump 到第一個 invalid field(`field.focus()` + `scrollIntoView({block: 'center'})`);對齊 Material / Atlassian 慣例 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **Error live region**:跨欄位 / async error 用 `aria-live="polite"` 容器宣告 — SR 在空閒時讀出,不中斷使用者打字
-- **Required indicator**:label 的 `*` 必加 `aria-label="required"` 或 hidden span(SR 朗讀「required」),純視覺 `*` SR 讀「asterisk」語義不清
-- **Color-only error 警告**:error border 紅色之外必有 icon 或文字(WCAG 1.4.1 不僅靠顏色)— DS error variant 自動 prefix `<AlertCircle/>` icon
+- **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'})`;focus 僅對 DOM `name`-locatable native input 生效,非 native 控件 fallback 為 scroll + error 視覺,見「v1 邊界」(b))
+- **Error 宣告**:`<FieldError>` 為 `role="alert"`(隱含 `aria-live="assertive"`,field.tsx:468)——error 文字一出現即由 SR 宣讀;children 有值才渲染(children-gated,非讀 Field.invalid)。目前**無**獨立 `aria-live="polite"` 容器,跨欄位 / async error 亦透過對應 field 的 `<FieldError>` 呈現
+- **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`「禁止事項」)
 
+**空值 / Loading(明文 N/A)**:本 spec 是跨 Field 控件的驗證時機原則(非 UI 元件)——空值渲染與 loading 狀態分屬各控件 spec(SSOT → `field-controls.spec.md`「null / undefined 值」+「Loading state」段)。
 
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
+## 相關
 
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `field.spec.md`
-- `link-input.spec.md`
-- `textarea.spec.md`
-- `time-picker.spec.md`
+- `field.spec.md` — Field wrapper 的 error 視覺 chrome(紅框 + error message slot)
+- `field-controls.spec.md` — form control 共用 state(disabled / readonly / invalid)
+- `../Input/input.spec.md` — `aria-required` / `aria-invalid` 實作端(input.tsx)
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `checkbox.spec.md`
 - `combobox.spec.md`
 - `date-picker.spec.md`
+- `field-controls.spec.md`
+- `field.spec.md`
+- `link-input.spec.md`
+- `select.spec.md`
+- `textarea.spec.md`
+- `time-picker.spec.md`

package/src/components/Field/index.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './field'
+export * from './field-types'

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

@@ -0,0 +1,270 @@
+/**
+ * useFormValidation — form-validation.spec.md 方法論的可執行層(SSOT executable arm)
+ *
+ * ── 定位 ──
+ * 把 `form-validation.spec.md` 的 9 條驗證方法論編成**不可配置的預設**——consumer 拿到就是
+ * canonical 行為,沒有 API 可以違反(M17「SSOT 必可傳播」:方法論從 prose 變 executable)。
+ *
+ * ── 實作基礎 ──
+ * 基於 react-hook-form(direct dependency,完全 wrapped 不外露——對齊 DS「基於 X」引擎慣例:
+ * DataTable 基於 TanStack / DatePicker 基於 react-day-picker / Toast 基於 sonner)。
+ * Consumer 不 install、不 import、看不到 RHF API。RHF 提供 values state / dirty 深比對 /
+ * errors store / resetField;驗證「時機」由本 hook own(RHF 的 mode/reValidateMode 不外露)。
+ *
+ * ── 與 Field 家族的關係(engine-agnostic 分層,field.spec.md「定位」段)──
+ * Field 保持純 layout + context(MUI FormControl 派,可用於 cell / view / 無引擎場景);
+ * 本 hook 住 form 層,錯誤經 consumer 一行 `<Field invalid={!!form.errors.x}>` 接入——
+ * Field 層零耦合。這是「A 派的自由 + B 派的 DX」混合位置。
+ *
+ * ── 方法論對應(form-validation.spec.md 規則 1-9)──
+ * 1 Focus 中不顯示錯誤     → 驗證只在 blur / submit 跑(無 onChange 驗證路徑)
+ * 2 Blur 時驗證            → getInputProps().onBlur 跑 validate[name]
+ * 3 Enter 等同 blur        → form 內 Enter 觸發 submit(全驗,超集);單行控件原生行為
+ * 4 Escape 取消回復原值    → getInputProps().onKeyDown Escape → resetField + 清 error
+ * 5 開始編輯立即清除 error → onChange 先清 errors[name](不論新值合法與否)
+ * 6 Blur 重新驗證          → 同 2(離開時重判)
+ * 7 Submit 驗證全部        → handleSubmit 對所有 validate keys 全跑(不依賴 blur 狀態)
+ * 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 /
+ *   Combobox / DatePicker / TimePicker;onChange 收 event 或裸值皆可)。Checkbox / Switch
+ *   (onCheckedChange)consumer 自接 setFieldValue。
+ * - focus-first-error 以 DOM `name` 屬性定位(native input 生效;非 native 控件 fallback
+ *   scroll 略過,errors 視覺仍由 Field 紅框 + FieldError 呈現)。
+ */
+import * as React from 'react'
+import { useForm } from 'react-hook-form'
+import type { FieldValues, Path, PathValue, DefaultValues } from 'react-hook-form'
+
+export interface UseFormValidationOptions<T extends FieldValues> {
+  /** 表單初始值(Update 場景 = 現有資料;dirty 比對基準) */
+  initialValues: T
+  /**
+   * 表單意圖,驅動 submit button 狀態(form-validation.spec.md「Submit Button 狀態」):
+   * - 'create'(default):submitDisabled 永遠 false(不讓使用者猜「為什麼按不了」)
+   * - 'update':submitDisabled = !isDirty(沒改就不用存;變更還原回 pristine 即再 disabled)
+   */
+  intent?: 'create' | 'update'
+  /**
+   * 格式驗證(blur 層,規則 2):single-field 純 syntax(email 格式 / 必填 / URL)。
+   * 回傳 error 訊息字串 = 不合法;undefined = 合法。
+   * 業務 / async / 跨欄位驗證**不要**放這裡——放 onSubmit 回傳(規則 9)。
+   */
+  validate?: Partial<Record<keyof T, (value: T[keyof T], values: T) => string | undefined>>
+  /**
+   * Submit handler(格式驗證全過後呼叫)。業務驗證(名稱重複 API / 跨欄位)在此判斷,
+   * 回傳 field-keyed error object(如 `{ name: '名稱已存在' }`)→ hook 自動 setError +
+   * anchor 到第一個錯誤(規則 9);回傳 undefined = 成功。
+   */
+  onSubmit: (values: T) => void | Partial<Record<keyof T, string>> | Promise<void | Partial<Record<keyof T, string>>>
+}
+
+export interface FormFieldInputProps<V = unknown> {
+  name: string
+  value: V
+  onChange: (eventOrValue: unknown) => void
+  onBlur: () => void
+  onKeyDown: (e: React.KeyboardEvent) => void
+}
+
+export interface UseFormValidationReturn<T extends FieldValues> {
+  /** 當前表單值(即時) */
+  values: T
+  /** field-keyed 錯誤訊息(餵 `<Field invalid>` + `<FieldError>`) */
+  errors: Partial<Record<keyof T, string>>
+  /** 任一欄位偏離 initialValues(深比對,還原回原值 = false) */
+  isDirty: boolean
+  /** 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) */
+  handleSubmit: (e?: React.FormEvent) => Promise<void>
+  /** 整表重置回 initialValues(清 errors + dirty) */
+  reset: () => void
+  /** Escape hatch:非 value/onChange 控件(Checkbox/Switch)手動寫值 */
+  setFieldValue: (name: keyof T & string, value: unknown) => void
+}
+
+/** onChange 收 event 或裸值皆可(對齊 Mantine getInputProps idiom):
+ *  native input event → e.target.value;自訂控件裸值(string / number / Date / array)→ 原樣。 */
+function extractValue(eventOrValue: unknown): unknown {
+  if (
+    eventOrValue &&
+    typeof eventOrValue === 'object' &&
+    'target' in eventOrValue &&
+    eventOrValue.target &&
+    typeof eventOrValue.target === 'object' &&
+    'value' in (eventOrValue.target as object)
+  ) {
+    return (eventOrValue.target as HTMLInputElement).value
+  }
+  return eventOrValue
+}
+
+/** 規則 8:focus + scroll 到第一個錯誤欄位。以 DOM name 屬性定位(native input);
+ *  找不到(非 native 控件)→ 靜默略過,error 視覺仍由 Field 紅框呈現。 */
+function focusFirstError(errorNames: string[]) {
+  // 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> {
+  const { initialValues, intent = 'create', validate, onSubmit } = options
+
+  // RHF 引擎(wrapped):驗證時機由本 hook own,故 RHF 自身 mode 鎖 onSubmit 且不掛 resolver
+  // (所有 setError/clearErrors 走手動,RHF 只當 state + dirty + errors store)。
+  const form = useForm<T>({
+    defaultValues: initialValues as DefaultValues<T>,
+    mode: 'onSubmit',
+    shouldFocusError: false, // 規則 8 自己 focus(RHF 依賴 register ref,本 hook 不走 register)
+  })
+
+  // 訂閱全表(表單尺度 re-render 可接受;formState.isDirty 深比對 vs defaultValues)
+  const values = form.watch()
+  const { errors: rhfErrors, isDirty } = form.formState
+
+  const errors = React.useMemo(() => {
+    const out: Partial<Record<keyof T, string>> = {}
+    for (const key of Object.keys(rhfErrors)) {
+      const msg = (rhfErrors as Record<string, { message?: string } | undefined>)[key]?.message
+      if (msg) out[key as keyof T] = msg
+    }
+    return out
+  }, [rhfErrors])
+
+  /** 規則 2/6:blur 驗證單一欄位 */
+  const validateField = React.useCallback(
+    (name: keyof T & string) => {
+      const fn = validate?.[name]
+      if (!fn) return
+      const current = form.getValues()
+      const message = fn(current[name], current)
+      if (message) form.setError(name as Path<T>, { type: 'format', message })
+      else form.clearErrors(name as Path<T>)
+    },
+    [form, validate],
+  )
+
+  const getInputProps = React.useCallback(
+    <K extends keyof T & string>(name: K): FormFieldInputProps<T[K]> => {
+      // 泛型 K 窄化到 Path<T> 需經 unknown(RHF Path 是 template-literal type,K 不直接 overlap)
+      const path = name as unknown as Path<T>
+      return {
+        name,
+        value: form.watch(path) as T[K],
+        onChange: (eventOrValue: unknown) => {
+          // 規則 5:開始編輯立即清除 error(不論新值合法與否,給修正空間)
+          if (form.getFieldState(path).error) form.clearErrors(path)
+          form.setValue(path, extractValue(eventOrValue) as PathValue<T, Path<T>>, {
+            shouldDirty: true,
+          })
+        },
+        // 規則 2:blur 驗證(focus 中永不驗 = 規則 1 自然成立)
+        onBlur: () => validateField(name),
+        // 規則 4:Escape 回復原值,不觸發驗證
+        onKeyDown: (e: React.KeyboardEvent) => {
+          if (e.key === 'Escape') {
+            form.resetField(path)
+            form.clearErrors(path)
+          }
+        },
+      }
+    },
+    [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[] = []
+      if (validate) {
+        for (const name of Object.keys(validate)) {
+          const fn = validate[name as keyof T]
+          if (!fn) continue
+          const message = fn(current[name as keyof T], current)
+          if (message) {
+            form.setError(name as Path<T>, { type: 'format', message })
+            formatErrors.push(name)
+          } else {
+            form.clearErrors(name as Path<T>)
+          }
+        }
+      }
+      if (formatErrors.length > 0) {
+        focusFirstError(formatErrors)
+        return
+      }
+      // 規則 9:業務 / async / 跨欄位驗證 defer 到 submit(onSubmit 回傳 field-keyed errors)
+      // 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)
+        }
+      } 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 as Path<T>, value as PathValue<T, Path<T>>, { shouldDirty: true }),
+  }
+}