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

package/src/components/Field/field.stories.tsx

@@ -2,7 +2,7 @@
 import type { Meta, StoryObj } from '@storybook/react'
 import * as React from 'react'
 import { Upload } from 'lucide-react'
-import { Field, FieldLabel, FieldDescription, FieldError, FieldGroup } from './field'
+import { Field, FieldLabel, FieldDescription, FieldError, FieldGroup, useFormValidation } from './field'
 import { Input } from '@/design-system/components/Input/input'
 import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
 import { Switch } from '@/design-system/components/Switch/switch'
@@ -611,3 +611,106 @@ export const SliderWithLiveNumberInput: Story = {
     )
   },
 }
+
+// ── 表單驗證(useFormValidation)──────────────────────────────────────────
+// form-validation.spec.md 可執行層 showcase:blur 驗證 / edit 清 error / Escape 回復 /
+// submit 全驗 + anchor 第一個錯誤 / 業務錯誤同軌 / Create·Update 按鈕不對稱。
+
+const EXISTING_PROJECT_NAMES = ['產品路線圖 Q3', '客服工單系統'] // 模擬「名稱重複」業務驗證(規則 9)
+
+function UpdateProjectSettingsForm() {
+  const [saved, setSaved] = React.useState(false)
+  const form = useFormValidation({
+    initialValues: { name: '產品路線圖', ownerEmail: 'pm@acme.com' },
+    intent: 'update', // Update:disabled-until-dirty(沒改就不用存)
+    validate: {
+      name: (v) => (String(v).trim() ? undefined : '專案名稱必填'),
+      ownerEmail: (v) => (/^\S+@\S+\.\S+$/.test(String(v)) ? undefined : 'Email 格式不正確'),
+    },
+    onSubmit: (values) => {
+      if (EXISTING_PROJECT_NAMES.includes(String(values.name).trim())) {
+        return { name: '此專案名稱已存在' } // 業務驗證(規則 9)→ 自動 setError + anchor
+      }
+      setSaved(true)
+    },
+  })
+  return (
+    <form onSubmit={form.handleSubmit} className="w-80" aria-label="專案設定">
+      <FieldGroup>
+        <Field required invalid={!!form.errors.name}>
+          <FieldLabel>專案名稱</FieldLabel>
+          <Input {...form.getInputProps('name')} />
+          <FieldDescription>改成「產品路線圖 Q3」可觸發 submit 業務驗證(名稱重複)</FieldDescription>
+          <FieldError>{form.errors.name}</FieldError>
+        </Field>
+        <Field required invalid={!!form.errors.ownerEmail}>
+          <FieldLabel>負責人 Email</FieldLabel>
+          <Input {...form.getInputProps('ownerEmail')} />
+          <FieldError>{form.errors.ownerEmail}</FieldError>
+        </Field>
+      </FieldGroup>
+      {/* 規則 4:內容 → action button = --layout-space-bottom(48px,commitment 前留白) */}
+      <div className="mt-[var(--layout-space-bottom)] flex items-center gap-2">
+        <Button type="submit" variant="primary" disabled={form.submitDisabled}>儲存變更</Button>
+        {saved && <span className="text-caption text-fg-muted">已儲存 ✓</span>}
+      </div>
+    </form>
+  )
+}
+
+function CreateProjectForm() {
+  const [created, setCreated] = React.useState(false)
+  const form = useFormValidation({
+    initialValues: { name: '', ownerEmail: '' },
+    intent: 'create', // Create:永遠 enabled(不讓使用者猜「為什麼按不了」)
+    validate: {
+      name: (v) => (String(v).trim() ? undefined : '專案名稱必填'),
+      ownerEmail: (v) => (/^\S+@\S+\.\S+$/.test(String(v)) ? undefined : 'Email 格式不正確'),
+    },
+    onSubmit: () => setCreated(true),
+  })
+  return (
+    <form onSubmit={form.handleSubmit} className="w-80" aria-label="建立專案">
+      <FieldGroup>
+        <Field required invalid={!!form.errors.name}>
+          <FieldLabel>專案名稱</FieldLabel>
+          <Input placeholder="例:結帳流程改版" {...form.getInputProps('name')} />
+          <FieldError>{form.errors.name}</FieldError>
+        </Field>
+        <Field required invalid={!!form.errors.ownerEmail}>
+          <FieldLabel>負責人 Email</FieldLabel>
+          <Input placeholder="pm@company.com" {...form.getInputProps('ownerEmail')} />
+          <FieldError>{form.errors.ownerEmail}</FieldError>
+        </Field>
+      </FieldGroup>
+      <div className="mt-[var(--layout-space-bottom)] flex items-center gap-2">
+        <Button type="submit" variant="primary">建立專案</Button>
+        {created && <span className="text-caption text-fg-muted">已建立 ✓</span>}
+      </div>
+    </form>
+  )
+}
+
+export const FormValidation: Story = {
+  name: '表單驗證 — useFormValidation 可執行層',
+  render: () => (
+    <div className="flex flex-wrap items-start gap-[var(--layout-space-loose)]">
+      <div className="flex flex-col gap-[var(--layout-space-tight)]">
+        <h3 className="text-body font-bold">更新:專案設定(disabled-until-dirty)</h3>
+        <p className="text-caption text-fg-muted max-w-80">
+          按鈕沒改不亮;打字中不報錯(blur 才驗);已出錯欄位一編輯立即清 error;
+          Escape 回復原值;空 submit / 格式錯 → anchor 到第一個錯誤欄位。
+        </p>
+        <UpdateProjectSettingsForm />
+      </div>
+      <div className="flex flex-col gap-[var(--layout-space-tight)]">
+        <h3 className="text-body font-bold">建立:新專案(永遠 enabled)</h3>
+        <p className="text-caption text-fg-muted max-w-80">
+          Create 按鈕永遠可按 —— 點了才驗證全部並 scroll 到第一個錯誤,
+          不讓使用者對著 disabled 按鈕猜原因。
+        </p>
+        <CreateProjectForm />
+      </div>
+    </div>
+  ),
+}

package/src/components/Field/field.tsx

@@ -536,3 +536,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

@@ -53,16 +53,37 @@
 
 兩者都透過 `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;對齊 DS「基於 X」引擎慣例:DataTable 基於 TanStack / DatePicker 基於 react-day-picker / Toast 基於 sonner)。RHF 提供 state / dirty 深比對 / errors store;驗證**時機**由本 hook own(RHF 的 mode / reValidateMode 不外露 = 不可配錯)。世界級對照:Atlassian `@atlaskit/form` 包 react-final-form 同構;MUI 靠第三方 binding(react-hook-form-mui)達成,本 DS 做成第一方。 <!-- @benchmark-unverified -->
+
+```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`** |
+| 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 定位)。
 
 ---
 

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

@@ -0,0 +1,242 @@
+/**
+ * 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 / display / 無引擎場景);
+ * 本 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`
+ *
+ * ── 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) */
+  submitDisabled: 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[]) {
+  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
+    }
+  }
+}
+
+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],
+  )
+
+  /** 規則 7/8/9:submit 全驗 + anchor 第一個錯誤 + 業務錯誤同軌 */
+  const handleSubmit = React.useCallback(
+    async (e?: React.FormEvent) => {
+      e?.preventDefault()
+      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)
+      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)
+      }
+    },
+    [form, validate, onSubmit],
+  )
+
+  return {
+    values,
+    errors,
+    isDirty,
+    // Submit Button 狀態 canonical:Create 永遠 enabled / Update disabled-until-dirty
+    submitDisabled: intent === 'update' ? !isDirty : false,
+    getInputProps,
+    handleSubmit,
+    reset: () => form.reset(),
+    setFieldValue: (name, value) =>
+      form.setValue(name as Path<T>, value as PathValue<T, Path<T>>, { shouldDirty: true }),
+  }
+}