react-forms

TanStack Form v1 を React で実装します。コアフック（`useForm()`、`useField()`、`form.Field`、`form.Subscribe`）、ネイティブの Standard Schema バリデーション（Zod ~12KB、Yup ~40KB、Valibot ~6KB、ArkType、Effect Schema — アダプターパッケージ不要）、デバウンス付き非同期バリデーション、`useActionState` による React 19 Server Actions との統合に対応します。

また、ドット記法による配列／ネストされたフィールド、副作用のリスナー（onMount／onChange／onBlur とデバウンス）、連動／フィールド間バリデーション、useStore セレクターによるリアクティビティ、Reset API、SSR／ハイドレーション（TanStack Start）、Devtools、React Native のパターンも扱います。これは TanStack Form の React スキルです。Next.js Server Actions に特化したバリアントについては nextjs-tanstack-form を、SOLID のファイル構成ルールについては solid-react を参照してください。

TanStack Form v1 のコア機能

エージェントのワークフロー（必須）

実装を始める前に、必ず 3 つのエージェントを並列で起動してください。それぞれ 1 回の Agent 呼び出しで、name を指定します。

1. fuse-ai-pilot:explore-codebase - 既存のフォームコンポーネントとバリデーションパターンを分析します
2. fuse-ai-pilot:research-expert - Context7／Exa を使って TanStack Form v1 の最新ドキュメントを確認します
3. mcp__context7__query-docs - Zod のバリデーションと React 19 Server Actions のパターンを確認します

実装後、検証のために fuse-ai-pilot:sniper を実行してください。

---

必須：SOLID 原則

必ず solid-react スキルの SOLID 原則を適用してください。

→ 完全なルールについては ../solid-react/SKILL.md を参照してください。

主なルール：

• ソースファイルは FUSE_SOLID_MAX_LINES の範囲内に収め、凝集性が低下したら責務ごとに分割します
• インターフェースは modules/[feature]/src/interfaces/ に配置します
• すべてのエクスポートに JSDoc を必須とします
• コンポーネントにビジネスロジックを記述しません

---

コアフック

フック	目的	ガイド
useForm()	バリデーション付きのフォームを初期化します	references/tanstack-form-basics.md
useField()	個別のフィールドを購読します	references/tanstack-form-basics.md
form.Field	フィールド用のレンダープロップコンポーネントです	references/tanstack-form-basics.md
form.Subscribe	フォームの状態変化を監視します	references/tanstack-form-basics.md

→ 詳しい使い方については references/tanstack-form-basics.md を参照してください。

---

バリデーションアダプター

TanStack Form v1（@tanstack/react-form 1.33.x）は Standard Schema をネイティブでサポートしています。スキーマ自体を validators に渡してください（onChange: userSchema）。アダプターは不要です。validatorAdapter と @tanstack/zod-form-adapter（最終リリースは 0.42.1、v1 より前のバージョンで、Zod 3 のみ対応）は削除されているか、廃止されています。

ライブラリ	使い方	最小バージョン	バンドルサイズ
Zod	validators: { onChange: schema }	3.24.0	~12KB
Yup	validators: { onChange: schema }	1.7.0	~40KB
Valibot	validators: { onChange: schema }	1.0.0	~6KB

→ Zod のパターンについては references/zod-validation.md を参照してください。 → 代替ライブラリについては references/yup-valibot.md を参照してください。

---

主な機能

非同期バリデーション

デバウンスと読み込み状態を使ったサーバー側のチェックです。 → references/async-validation.md を参照してください。

Server Actions（React 19）

useActionState との統合とプログレッシブエンハンスメントに対応します。 → references/server-actions.md を参照してください。

配列とネストされたフィールド

動的なフィールド配列と、ネストされたオブジェクトのドット記法に対応します。 → references/arrays-nested.md を参照してください。

TypeScript との統合

Zod スキーマと defaultValues から完全な型推論を行います。 → references/typescript.md を参照してください。

shadcn/ui との統合

shadcn のスタイルを適用したフィールドラッパーコンポーネントを使用します。 → references/shadcn-integration.md を参照してください。

リスナー（副作用）

デバウンス付きの onMount、onChange、onBlur、onSubmit に対応します。 → references/listeners.md を参照してください。

連動フィールド

フィールド間バリデーションと依存するドロップダウンに対応します。 → references/linked-fields.md を参照してください。

リアクティビティとパフォーマンス

useStore セレクターと粒度の細かい購読に対応します。 → references/reactivity.md を参照してください。

Reset API

カスタム値を指定して、フォームとフィールドをリセットします。 → references/reset-api.md を参照してください。

SSR とハイドレーション

TanStack Start との統合とサーバー状態のマージです。 → references/ssr-hydration.md を参照してください。

開発者ツール

@tanstack/react-form-devtools でフォームの状態をデバッグします。 → references/devtools.md を参照してください。

React Native

TextInput を使用するモバイル固有のパターンです。 → references/react-native.md を参照してください。

Standard Schema

ArkType と Effect Schema をサポートしています。 → references/standard-schema.md を参照してください。

---

テンプレート

テンプレート	用途
templates/basic-form.md	Zod を使ったログイン／サインアップ
templates/multi-step-form.md	ステップごとの検証を行うウィザード
templates/dynamic-fields.md	フィールド配列の追加／削除
templates/file-upload-form.md	プレビュー付きファイル入力
templates/server-action-form.md	React 19 Server Actions
templates/optimistic-form.md	useOptimistic との統合
templates/nested-form.md	ドット記法によるネストされたフィールド
templates/search-form.md	デバウンス付き検索
templates/conditional-fields.md	値に応じた表示／非表示
templates/form-composition.md	再利用可能なフィールドコンポーネント
templates/listeners-form.md	副作用と自動保存
templates/linked-fields-form.md	フィールド間の検証
templates/reactivity-form.md	パフォーマンスの最適化
templates/reset-form.md	フォーム／フィールドのリセットパターン
templates/ssr-form.md	SSR とハイドレーション
templates/devtools-form.md	開発者ツールとの統合
templates/react-native-form.md	React Native フォーム

---

ベストプラクティス

1. 検証：カスタム正規表現ではなく、Zod／Yup／Valibot を使用します
2. 非同期処理：サーバー検証をデバウンスします（300～500ms）
3. エラー：field.state.meta.errors を表示します
4. ネスト：ドット記法（address.street）を使用します
5. 配列：pushValue／removeValue とともに mode="array" を使用します
6. TypeScript：z.infer<typeof schema> で型を推論します

---

禁止事項（アンチパターン）

• ❌ フォームの状態に useState を使用 → useForm() を使用します
• ❌ 正規表現による検証 → Zod／Yup／Valibot を使用します
• ❌ 非同期処理にデバウンスを設定しない → onChangeAsyncDebounceMs を使用します
• ❌ コンポーネント内で検証する → スキーマに移します
• ❌ onChange を直接使用する → field.handleChange を使用します
• ❌ TypeScript の型を定義しない → z.infer<typeof schema> を使用します