tanstack-form

TanStack Form

TanStack Form v1（npm latest）に関わる作業では、このスキルを使用してください。特に、@tanstack/react-form、フォームの状態管理、バリデーション、アプリ内で再利用するフォームフック、SSR アダプター、場当たり的な React フォーム処理からの移行、v2 アルファ版への移行計画が対象です。

ワークフロー

1. コードを変更する前に、ローカルのフォームスタックを確認します。
   • @tanstack/react-form、@tanstack/form-core、SSR アダプター、開発者ツール、React、スキーマライブラリ、UI ライブラリ、テストユーティリティのパッケージバージョン。
   • フォームのパターン：単独の useForm、アプリ全体で使う createFormHook、ネストされた withForm、再利用可能な withFieldGroup、SSR アダプターのフォーム、または React Native。
   • バリデーションの目的：フィールド単位、フォーム単位、Standard Schema、非同期バリデーター、動的な再バリデーション、サーバーバリデーション、または送信時のエラー。
   • レンダリング上の要件：制御フィールド、ラベル、エラー表示、フォーカス管理、送信状態、アクセシビリティへの期待。
2. 動作やバージョンが重要な場合は、最新のドキュメントとパッケージの情報を確認します。source-map.mdから始めてください。
3. インストール、コア API、useForm、form.Field、createFormHook、アプリ用フィールド、サブスクリプション、非同期の初期値、UI ライブラリとの接続については、setup-core.mdを使用してください。
4. フィールド／フォームのバリデーター、Standard Schema、非同期バリデーション、動的バリデーション、サーバーエラー、カスタムエラー、送信メタデータ、変換後の値については、validation-state.mdを使用してください。
5. 大規模なフォーム、再利用可能なアプリ用フォームフック、withForm、withFieldGroup、配列、FormGroup、リンクされたフィールド、リスナーについては、composition-arrays-groups.mdを使用してください。
6. TanStack Start、Next.js App Router、Remix、サーバーバリデーション、開発者ツール、デバッグ、アクセシビリティ、本番環境での確認については、ssr-production.mdを使用してください。
7. リポジトリに 2.0.0-alpha.* がインストールされている場合、またはユーザーが Form v2 について尋ねた場合に限り、v2-alpha.mdを使用してください。v1 のコードに v2 のパターンを適用しないでください。

実装上の判断

• defaultValues または共有の formOptions から型を推論することを優先してください。ローカルのコードベースですでに必要とされている場合を除き、広範な useForm<MyType>() ジェネリクスの追加は避けてください。
• 小規模なフォームや単独のフォームには、通常の useForm と form.Field を使用してください。製品のフォームやデザインシステムとの統合では、フィールドとフォームのコンポーネントがあらかじめバインドされた createFormHook を優先してください。
• TanStack Form のフィールドは制御フィールドとして扱ってください。フィールド API に対して、value、onBlur、onChange を明示的に接続してください。
• サブスクライブする対象は意図的に選んでください。UI の一部には form.Subscribe を使用し、コンポーネントのロジックには useSelector(form.store, selector) を使用してください。非推奨の useStore より useSelector を優先してください。ストア全体へのサブスクリプションは避けてください。
• バリデーションのタイミングは意図的に設定してください。慣例で決めるのではなく、UX に基づいて onChange、onBlur、onSubmit、onMount、onDynamic、非同期バリデーターを選択してください。
• Standard Schema のバリデーションは入力値を検証しますが、変換後の出力を onSubmit に渡すわけではありません。変換後のスキーマ出力が必要な場合は、onSubmit の中でパースしてください。
• フィールド間のバリデーションには onChangeListenTo または onBlurListenTo を使用し、リセット、分析、自動保存などの副作用には listeners を使用してください。
• マルチステップフォームで最終的に送信する値をまとめ、バリデーションの状態を共有する必要がある場合は、個別に分離したフォームより FormGroup を優先してください。
• SSR フレームワークでは、アダプターの formOptions を通じてフォームの形状を共有し、createServerValidate でサーバー側のバリデーションを行い、mergeForm と useTransform で返されたフォーム状態をマージしてください。

検証

リポジトリに既存のチェックがある場合は、そちらを優先してください。TanStack Form に影響する変更では、関連する項目を適切に選んで実施してください。

• フィールド名、深い階層のキー、デフォルト値、バリデーター、送信メタデータ、フィールドグループ、SSR アダプターのインポートについて型チェックを行います。
• バリデーションのタイミング、非同期のデバウンス、送信エラー、配列の変更、連動するフィールド、リスナーの副作用、リセットとデフォルト値について、対象を絞ったテストを行います。
• 制御された入力、エラーの表示、送信ボタンの無効化または aria-disabled、無効な状態での送信時のフォーカス、デフォルト値の読み込み、サーバーから返されたエラーについて、ブラウザーでスモークテストを行います。
• TanStack Start、Next.js、Remix のアダプターフローを変更する場合は、SSR とアクションのテストを行います。
• 状態が古いように見える場合は、Devtools またはデバッグで状態を確認します。明示的にサブスクライブしない限り、フォームの状態はリアクティブではありません。