Open History to see the last commit
1# TanStack Form V2 Skill Spec
2β
3Status: reviewed, Phase 5 finalized.
4β
5This reviewed artifact follows the `pnpm intent:scaffold` domain-discovery workflow. It is intentionally adapter-first: user-facing guidance starts from `@tanstack/react-form`, with `@tanstack/form-core` used as the source of concepts and behavior rather than as a workflow entrypoint.
6β
7## Scope
8β
9In scope:
10β
11- React form composition with `useForm`, `form.Field`, `form.ArrayField`, `form.Subscribe`, app-form helpers, and field groups.
12- Standard Schema-compatible schema usage.
13- Choosing between default form options, `strictSchema`, and `looseSchema`.
14- Query-like async defaults and mutation-like submit handling.
15- Error visibility callback workflows.
16- Split-form helper types and reusable validation or visibility policy modules.
17- Type error diagnosis for schema/form composition.
18- Authoring richer React examples.
19β
20Out of scope for this pass:
21β
22- Devtools as an entrypoint.
23- Migration guidance.
24- Schema metadata extraction, such as automatically deriving required labels.
25- TanStack Form owning transient or non-validation error state.
26- Teaching UI-library behavior as part of TanStack Form itself.
27- Solid-first coverage.
28β
29## Hard Do Nots
30β
31- Do not type assert to make TanStack Form code compile. The library is built around inference, and assertions are usually a sign that the code is fighting the API.
32- Do not write field names like ``name={`users[${index}].name` as const}``; `name` is inferred without the assertion.
33- Do not annotate render-prop children as `any`; field children already receive inferred field APIs.
34- Do not shim field prop types by hand, such as `{ value: string }`; use inferred render-prop types, `FieldWithValue<T>`, or `AnyFieldApi` when a reusable component needs an explicit field prop type.
35- Do not treat validation errors and transient errors as the same thing. Errors stored from validators or `onSubmit` block the user from submitting.
36- Do not store query/network/framework transient failures as form validation errors. Most query libraries already own transient error state; use that state instead.
37- Do not throw validation errors from validators or `onSubmit`; validation errors must be returned values, such as `createValidationError` or `parseIssues`.
38- Do not type a shared section as `form: FormA | FormB` where each form is a different `ReactFormType`; TypeScript cannot make sense of that union. Use field groups for shared sections that need to work across different forms.
39β
40## Proposed Skills
41β
42### 1. React Form Composition Setup
43β
44Purpose: Help users build adapter-first React forms, reusable field components, app-form setups, field groups, arrays, and UI-library bindings.
45β
46Primary APIs:
47β
48- `useForm`
49- `ReactFormType`
50- `FieldWithValue`
51- `AnyFieldApi`
52- `formOptions`
53- `createFormHook`
54- `form.Field`
55- `form.ArrayField`
56- `form.Subscribe`
57- `form.FormGroup`
58- `withFields`
59β
60Core guidance:
61β
62- Start from `@tanstack/react-form`, not `@tanstack/form-core`.
63- Use render-prop field APIs and subscriptions for state reads.
64- Treat `useForm` and `useAppForm` as stable form creation hooks, not reactive state reads by themselves.
65- Use `useSelector` or `form.Subscribe` when component output must update in response to form state.
66- Use app-form helpers when an application wants reusable field and form components.
67- Keep shared form options submit-agnostic when child components need to accept forms with different `onSubmit` handlers.
68- Use `ReactFormType<typeof sharedFormOptions>` as one option for splitting a known form into child sections that receive the form as a prop.
69- Do not use unions like `ReactFormType<typeof formAOptions> | ReactFormType<typeof formBOptions>` for shared sections; use field groups when one section should bind into multiple different forms.
70- Use AppForm to reduce repeated field JSX boilerplate. Use split form sections to reduce component nesting. Use field groups for reusable sections that bind to different form paths or different forms.
71- Let field `name` props and render-prop children infer their types; use `FieldWithValue<T>` or `AnyFieldApi` for explicit reusable field component props.
72- `form.Field` may bind to an array value. It treats that array immutably like any other field value, so changing one element changes the field `value` and rerenders consumers of the whole array field.
73- Use `form.ArrayField` when the array is a rendering boundary for child fields or list items, and those child fields are the reactive units the example cares about.
74- Use array helpers for array mutations and reorders.
75β
76Important failure modes:
77β
78- Adding `as const`, `as any`, render-prop `field: any`, or other assertions to force form code to compile.
79- Shimming field prop types by hand instead of using inferred field types, `FieldWithValue<T>`, or `AnyFieldApi`.
80- Reading from the stable `useForm` or `useAppForm` return and expecting the component to re-render as form state changes.
81- Importing core directly in examples or application code.
82- Rendering app field components outside their required app-form or field context.
83- Making a reusable child form prop too specific by baking in an `onSubmit` type.
84- Splitting a form by hand-writing a large form prop type instead of deriving it from shared options with `ReactFormType`.
85- Typing a shared section as a union of multiple `ReactFormType` forms instead of using field groups.
86- Using `form.Field` to render a list of child fields, then being surprised that item changes rerender the whole array-value consumer.
87- Treating `form.ArrayField` as required for every array-typed value, instead of using it when the array will render child fields or list items.
88- Mutating arrays manually and desynchronizing values from field meta.
89β
90Source trail:
91β
92- `packages/react-form/src/ReactForm/Components.public.ts`
93- `packages/react-form/src/ReactForm/ReactFormApi.lib.tsx`
94- `packages/react-form/src/Subscribe.public.tsx`
95- `packages/react-form/src/ReactForm/fieldSubscriptions.lib.ts`
96- `packages/react-form/src/AppForm/createFormHook.public.ts`
97- `packages/react-form/src/AppForm/contexts.lib.ts`
98- `docs/reference/type-aliases/FieldWithValue.md`
99- `docs/reference/type-aliases/AnyFieldApi.md`
100- `docs/framework/react/reference/type-aliases/ReactFormType.md`
101- `packages/react-form/tests/submit-return.test-d.tsx`
102- `packages/form-core/src/FormApi/array-methods.lib.ts`
103- `packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts`
104- `packages/form-core/src/FieldApi/fieldState.lib.ts`
105- `examples/react/array/src/index.tsx`
106- `examples/react/basic-splitting-form/src/index.tsx`
107- `examples/react/basic-splitting-form/src/FormSection.tsx`
108- `examples/react/basic-splitting-form/src/StringField.tsx`
109- `examples/react/basic-splitting-form/src/FieldError.tsx`
110- `examples/react/ui-integration-shadcn/src/components/form/app-form.ts`
111β
112### Cross-Cutting: Reusable Form Policies
113β
114Purpose: Help agents recognize when form behavior should be extracted into a named reusable helper rather than repeated inline.
115β
116Primary APIs:
117β
118- `ReactFormType`
119- `createErrorVisibility`
120- `createValidator`
121- `createValidators`
122- shared `formOptions` / `appFormOptions`
123β
124Core guidance:
125β
126- Use `ReactFormType<typeof sharedFormOptions>` as the helper type for split form sections that receive a `form` prop.
127- Treat `ReactFormType` splitting as one composition option, not a general replacement for AppForm or field groups.
128- AppForm reduces repeated field JSX boilerplate; split sections reduce nesting in a known form; field groups cover shared sections across different forms or field paths.
129- Prefer form-level `errorVisibility` callbacks over scattered local patterns like `const showErrors = field.meta.isTouched && field.meta.isInvalid`.
130- Use helper functions mainly when a callback or validator config deserves a semantic name that preserves intent.
131- Extract validator configs with `createValidator` or `createValidators` when trigger timing, debounce, `bailIfInvalid`, or `skipOnSubmit` policy is complex enough to name.
132- Use comments or JSDoc on named helpers to explain behavior intent, such as why errors wait for blur or submit, or why a validator uses a `rewardEarlyPunishLate` policy.
133- Keep reusable policies value-agnostic unless they are intentionally tied to a specific form shape; inline callbacks are better when typed values are required.
134β
135Important failure modes:
136β
137- A split form loses field-name inference because the child prop type was hand-written.
138- A shared section accepts `FormA | FormB` and TypeScript cannot narrow field names or form methods enough to make the section usable.
139- Error display behavior is scattered through local `showErrors` variables instead of being controlled by form-level `errorVisibility`.
140- A complex visibility workflow is duplicated inline and later examples preserve code shape but lose the user-workflow reason.
141- Validator trigger settings are copied without explanation, so agents cannot tell whether `blur`, `change`, debounce, or `bailIfInvalid` is intentional.
142- A reusable visibility function tries to read a concrete `state.values.name` even though reusable visibility callbacks are form-agnostic.
143β
144Source trail:
145β
146- `examples/react/basic-splitting-form/src/FormSection.tsx`
147- `examples/react/basic-splitting-form/src/sharedForm.ts`
148- `packages/react-form/tests/submit-return.test-d.tsx`
149- `packages/form-core/tests/validation.test.ts`
150- `packages/form-core/tests/validation.test-d.ts`
151- `examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx`
152β
153### 2. Choosing Form Options Modes
154β
155Purpose: Help users decide between default `formOptions`, `strictSchema`, and `looseSchema`.
156β
157Primary APIs:
158β
159- `formOptions`
160- `formOptions.strictSchema`
161- `formOptions.looseSchema`
162- `appFormOptions`
163- `appFormOptions.strictSchema`
164- `appFormOptions.looseSchema`
165β
166Core guidance:
167β
168- Treat the option helpers as runtime identity helpers with type-level meaning.
169- Use default `formOptions` when the form should be inferred from `defaultValues`; the default values are taken at face value and that type flows into validators and callbacks.
170- Default `formOptions` is especially useful for callback-based validation because callback `value` is already typed from the form defaults.
171- Use `strictSchema` when the schema is the source of typing and acts as a transforming pipeline from input type to output type.
172- In `strictSchema`, `defaultValues` should type-check against the schema input type. If they do not align, the defaults should produce type errors.
173- Use `looseSchema` when the schema is a ruleset for confirming valid output, but editable defaults need nullable or undefined values, such as a date field that starts as `null`.
174- In `looseSchema`, default values must still align with the schema shape, but properties may also be `null` or `undefined` where editing requires it.
175- In both schema modes, callbacks may not have useful inference unless there is a schema in the validator array for the helper to infer from.
176- In both schema modes, `onSubmit` should read the parsed transform output from `validatorOutputs` rather than raw `value`.
177- Treat pipeline-vs-ruleset as TanStack Form guidance, not a Standard Schema concept. Standard Schema only gives the shared validation/typing interface.
178- Explain the mental model as: is this schema a pipeline of constraints/transforms, or a firewall that only lets valid values through?
179- List current Standard Schema-capable libraries as examples with a general leaning, not as hard categories.
180- Zod generally leans ruleset/firewall for form work, while explicit transforms/codecs can still make a Zod schema pipeline-like.
181- Valibot generally leans pipeline because its docs center `pipe` and validation/transformation actions.
182- ArkType is mixed: structural constraints often read like a firewall, while morphs/pipes can make it pipeline-like.
183- Effect Schema often leans pipeline/codec when used as an encoded-to-decoded boundary.
184β
185Important failure modes:
186β
187- Expecting `strictSchema` or `looseSchema` to add runtime validation by itself.
188- Using default `formOptions` while expecting the schema to be the source of the form type.
189- Using strict schema mode for a form whose editable UI states cannot satisfy the schema type.
190- Using `looseSchema` but providing default values that no longer match the schema shape at all.
191- Using schema modes without putting a schema in the validator array, then expecting callbacks to infer from that schema.
192- Using loose schema mode for a true pipeline and then reading raw `value` as if it were parsed output.
193- Reading `value` in `onSubmit` for schema-mode forms instead of reading the corresponding `validatorOutputs` entry.
194- Treating all Zod `input` and `output` differences as a real pipeline decision.
195β
196Source trail:
197β
198- `packages/form-core/src/utils.public.ts`
199- `packages/react-form/src/AppForm/appFormOptions.public.ts`
200- `packages/form-core/tests/validation.test.ts`
201- `packages/form-core/tests/validation.test-d.ts`
202- `examples/react/ui-integration-shadcn/src/app/booking/schema.ts`
203- `examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx`
204- `https://standardschema.dev/`
205- `https://zod.dev/library-authors`
206- `https://valibot.dev/guides/integrate-valibot/`
207- `https://arktype.io/docs/integrations`
208- `https://effect.website/docs/schema/standard-schema/`
209β
210### 3. Schema Driven Forms
211β
212Purpose: Help users take a Standard Schema-compatible schema and wire it into validation, field errors, submit output, and type inference.
213β
214Primary APIs:
215β
216- `validators`
217- `FormSubmitContext.validatorOutputs`
218- `parseIssues`
219- `createValidationError`
220β
221Core guidance:
222β
223- Configure schema validation through validators.
224- Extract reusable validator trigger configs with `createValidator` or `createValidators` when the behavior is complex enough to need a semantic name.
225- Read parsed schema output from `onSubmit` context's `validatorOutputs`; raw `value` remains form state.
226- Route submit validation errors as returned values through `createValidationError` or `parseIssues`; do not throw them.
227- Let Standard Schema issue paths route nested and array field errors when possible.
228- Keep UI metadata explicit or schema-library-specific; Standard Schema does not standardize it.
229β
230Important failure modes:
231β
232- Expecting schema output to replace form `value`.
233- Returning or throwing raw schema errors from submit code and expecting field errors.
234- Throwing validation errors instead of returning `createValidationError` or `parseIssues` values.
235- Manually mapping nested issue paths incorrectly.
236- Duplicating validator trigger, debounce, submit, or bail policy inline without documenting why that behavior exists.
237- Trying to build general UI metadata extraction from Standard Schema.
238β
239Source trail:
240β
241- `packages/form-core/src/standardSchema.public.ts`
242- `packages/form-core/src/standardSchema.lib.ts`
243- `packages/form-core/src/FormApi/FormApi.public.ts`
244- `packages/form-core/tests/validation.test.ts`
245- `packages/form-core/tests/FormApi/submission-handling.spec.ts`
246- `examples/react/field-groups/src/index.tsx`
247β
248### 4. Query Backed Forms
249β
250Purpose: Help users combine form state with query-like async defaults and mutation-like submit calls.
251β
252Primary APIs:
253β
254- `useForm({ defaultValues })`
255- `onSubmit`
256- `form.reset`
257- `createValidationError`
258- `parseIssues`
259β
260Core guidance:
261β
262- Do not feed maybe-undefined query data into the form by itself; choose an explicit default-values plan.
263- Approach 1: do not mount the fields until the query is finished. The whole form can also be gated so the first mounted form state is populated with correct data.
264- Approach 2: define a static shape-complete `emptyFormValues` object and pass defaults as `query.data ?? emptyFormValues`.
265- Neither approach is preferred globally; choose based on the desired loading and visual UI language.
266- Gating fields changes the UI because fields or the whole form appear only after data is ready. The fallback approach can render the form immediately, often with loading or placeholder state around it.
267- Update defaults when async data arrives and rely on touched-field preservation for user edits.
268- Separate transient errors from validation errors.
269- Use an async promise for the endpoint call inside `onSubmit` so `isSubmitting` reflects the request.
270- Catch submit failures only when the endpoint can return validation errors that should be converted into returned `createValidationError` or `parseIssues` values.
271- Transient submit failures may throw or reject; the form will set `isSubmitSuccessful` to false, and query/framework state should preserve the transient error details.
272- Leave transient query, network, and framework failures in the query/framework error state instead of converting them into form validation errors.
273- Use reset options deliberately when replacing both values and default baselines.
274β
275Important failure modes:
276β
277- Treating initial `undefined` query data as a final form shape.
278- Passing `query.data` directly as defaults without either gated mounting or an `emptyFormValues` fallback.
279- Gating fields without accounting for the different loading UI, or rendering fallback values without communicating that query data is still loading.
280- Overwriting touched user edits when async defaults arrive.
281- Starting an endpoint call inside `onSubmit` without returning or awaiting its promise, so `isSubmitting` does not cover the request.
282- Turning transient network or server failures into validation errors and accidentally blocking future submits.
283- Throwing validation errors from `onSubmit` instead of returning validation values.
284- Treating a rejected transient `onSubmit` as something that should produce visible field errors.
285β
286Source trail:
287β
288- `packages/react-form/tests/useForm.spec.tsx`
289- `packages/form-core/src/FormApi/FormApi.lib.ts`
290- `packages/form-core/src/FormApi/FormApi.public.ts`
291- `packages/form-core/tests/FormApi/default-value.spec.ts`
292- `packages/form-core/tests/FormApi/submission-handling.spec.ts`
293β
294Open evidence gap: the IDE referenced `examples/react/tanstack-query/src/App.tsx`, but this checkout did not contain `examples/react/tanstack-query`.
295β
296### 5. Error Visibility Workflows
297β
298Purpose: Help users implement policies such as "show after blur", "show after submit", or "show after blur or submit".
299β
300Primary APIs:
301β
302- `errorVisibility`
303- `createErrorVisibility`
304- `createValidator`
305- `createValidators`
306- `fieldState.meta`
307- `state.submissionAttempts`
308- `form.FormGroup`
309β
310Core guidance:
311β
312- `errorVisibility` is callback-based.
313- Use form-level `errorVisibility` to control default visible-error behavior instead of scattering local checks like `field.meta.isTouched && field.meta.isInvalid`.
314- Reusable visibility policies created with `createErrorVisibility` should be value-agnostic.
315- Use `createErrorVisibility`, `createValidator`, and `createValidators` mainly when a policy benefits from a semantic name or intent-focused comments/JSDoc.
316- Inline callbacks can use the consuming form's typed values.
317- Visibility callbacks receive pre-filter field meta, not visible errors or validity.
318- Grouped forms scope submission attempts to the nearest group.
319β
320Important failure modes:
321β
322- Writing string presets such as `errorVisibility: 'touched'`.
323- Repeating local `showErrors` expressions across fields instead of setting the form's default error visibility behavior.
324- Inspecting `fieldState.meta.errors` or validity inside the visibility callback.
325- Expecting reusable `createErrorVisibility` callbacks to know a concrete form value shape.
326- Copying complex visibility or validator policy inline without documenting the workflow intent.
327- Forgetting group-scoped submission attempts in wizard or section-level flows.
328β
329Source trail:
330β
331- `packages/form-core/src/validation.public.ts`
332- `packages/form-core/src/FieldApi/fieldState.lib.ts`
333- `packages/form-core/tests/validation.test-d.ts`
334- `packages/form-core/tests/FormApi/validation.spec.ts`
335- `packages/form-core/tests/FormGroupApi/FormGroupApi.spec.ts`
336- `examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx`
337β
338### 6. Type Error Debugging
339β
340Purpose: Help users interpret large TypeScript errors from schemas, option modes, field groups, reusable forms, and adapter APIs.
341β
342Primary APIs and concepts:
343β
344- `ReactFormType`
345- `formOptions`
346- `appFormOptions`
347- `createErrorVisibility`
348- `createValidators`
349- schema `strictSchema` / `looseSchema`
350- field component `strict` / `loose`
351- field group `strict` / `loose`
352- `DeepKeys`
353- `DeepValue`
354- public `atom` APIs
355β
356Core guidance:
357β
358- Do not use type assertions to silence TanStack Form type errors; preserve inference and fix the mismatched boundary.
359- Classify the error by boundary: schema option mode, schema output, submit return, reusable child form props, error visibility state, validator helper arity, form group scope, field group virtual path/binding, field component brand, deep-key path, or public/private API mismatch.
360- Treat a `ReactFormType` union in a shared section as a design issue, not a TypeScript problem to assert through; reach for field groups instead.
361- Do not confuse schema strict/loose with field component or field group strict/loose.
362- For long errors, find the first concrete path, value, validator, or submit-return mismatch and ignore the expanded generic machinery around it.
363- Reusable `createErrorVisibility` callbacks are form-agnostic; if a type error mentions `unknown` values, use an inline callback for form-specific values.
364- `createValidators` type errors often mean the number of run functions does not match the number of option configs.
365- FormGroup type errors often mean the code used a root-form path/value where the group expects group-scoped paths/values.
366- Field-group type errors often mean the code used real form paths where virtual paths are expected, passed an incomplete binding map, or chose `strict` when the real path is only loosely compatible.
367- Deep-key path errors usually point to path shape: arrays use bracket segments such as `users[${number}].name`, and array helpers only accept paths whose value includes an array.
368- Look for the first meaningful generic mismatch rather than the full expanded error wall.
369- Prefer source-backed explanation over broad TypeScript folklore.
370β
371Important failure modes:
372β
373- Adding assertions like `as const`, `as any`, or `(field: any)` instead of letting form names and children infer.
374- Hand-writing shim field prop types instead of using inferred props, `FieldWithValue<T>`, or `AnyFieldApi`.
375- Typing a shared section as `ReactFormType<typeof formAOptions> | ReactFormType<typeof formBOptions>`.
376- Expecting a reusable `createErrorVisibility` callback to read concrete form values.
377- Calling `createValidators` with fewer or more run functions than option configs.
378- Using root-form field names or values inside a `FormGroup` validator or grouped field.
379- Passing real form paths into a field group API where virtual paths are required.
380- Providing an incomplete `withFields` binding map, passing the internal defined-fields object as a binding, or omitting the required `form` prop.
381- Reading `form.store` or `field.store` instead of public `atom` APIs.
382- Treating `fieldComponent.strict/loose` as schema mode selection.
383- Passing a submit-specific form type to a reusable child that should accept several submit handlers.
384- Binding a strict field group slot to a field path whose value is only loosely compatible.
385β
386Source trail:
387β
388- `packages/form-core/tests/validation.test-d.ts`
389- `packages/form-core/tests/deep-keys.test-d.ts`
390- `packages/react-form/tests/submit-return.test-d.tsx`
391- `packages/react-form/tests/FormGroup.test-d.tsx`
392- `packages/react-form/tests/FieldGroupApi.test-d.tsx`
393- `packages/react-form/src/AppForm/getFormHookHelpers.public.ts`
394- `packages/react-form/src/FieldGroup/withFields.public.ts`
395β
396### 7. Examples Authoring
397β
398Purpose: Help Codex scaffold substantial maintainer examples for testing, future documentation, and user reference.
399β
400Primary example areas:
401β
402- Basic form and submit handling.
403- Schema-driven form.
404- Query-backed form.
405- Error visibility workflow.
406- App-form and UI-library integration.
407- Field groups.
408- Arrays and reorder behavior.
409β
410Core guidance:
411β
412- Examples are scaffolding targets for maintainers in this private repository, and future users experience them as reference examples.
413- Examples should be adapter-first and user-journey-shaped.
414- Combine features when real workflows combine them, such as schema mode plus async defaults plus submit validation plus visibility policy.
415- Keep boundaries explicit: TanStack Form handles validation and form state; query/framework code owns transient errors; UI libraries own visual behavior.
416- Show reactive state reads with `useSelector` or `form.Subscribe`; do not imply the stable hook return is itself reactive.
417- Prefer realistic examples over minimal API proofs once behavior has test coverage.
418β
419Important failure modes:
420β
421- Writing barren examples that resemble core tests more than user workflows.
422- Modeling complex DnD multi-list state as a single indexed array and creating UI races.
423- Letting native reset behavior fight form reset semantics.
424- Reading form state from the stable hook return without a selector or subscription, then wondering why UI does not update.
425- Reading submit state outside `form.Subscribe` and missing updates.
426β
427Source trail:
428β
429- `examples/react/basic/src/index.tsx`
430- `examples/react/array/src/index.tsx`
431- `examples/react/basic-splitting-form/src/index.tsx`
432- `examples/react/field-groups/src/index.tsx`
433- `examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx`
434- `examples/react/ui-integration-shadcn/src/app/booking/booking-form.tsx`
435- `examples/react/ui-integration-dnd-kit/src/singleList/index.tsx`
436- `examples/react/ui-integration-dnd-kit/src/twoLists/index.tsx`
437β
438## Cross-Skill Relationships
439β
440- React Form Composition Setup is the base skill for all example work.
441- Reusable Form Policies sits between React Form Composition Setup, Error Visibility Workflows, and Type Error Debugging.
442- Choosing Form Options Modes feeds Schema Driven Forms and Type Error Debugging.
443- Schema Driven Forms feeds Query Backed Forms when submit returns server-side validation.
444- Error Visibility Workflows is often layered on top of Schema Driven Forms and Query Backed Forms.
445- Examples Authoring should compose the other skills into realistic maintainer scaffolds that can later serve as references.
446β
447## Cross-Skill Tensions
448β
449- Schema strictness vs editable defaults: strict schema typing helps submit output, but editable forms often need nullable or undefined intermediate values.
450- Query loading UI vs form initialization: gated mounting gives correct first form state, while `emptyFormValues` lets the UI render immediately.
451- Validation state vs transient state: validation errors block submit, while query/network/framework failures should remain outside form validation state.
452- Reuse vs inference boundaries: reusable sections are valuable, but assertions, hand-written field props, or `ReactFormType` unions break the intended inference model.
453β
454## Remaining Gaps
455β
456- Query Backed Forms: the IDE referenced `examples/react/tanstack-query/src/App.tsx`, but this checkout did not contain `examples/react/tanstack-query`. Query-backed guidance is reviewed from tests and maintainer interview, and should be exercised by scaffolding a realistic example later.
457β
458## Phase 5 Finalization
459β
460Resolved in the detail interview:
461β
462- Hard do-nots, especially no type assertions and no transient errors as validation errors.
463- Schema mode wording for default `formOptions`, `strictSchema`, and `looseSchema`.
464- Query-backed default-value strategies and their visual loading language.
465- Async `onSubmit` behavior, including `isSubmitting`, `isSubmitSuccessful`, returned validation values, and thrown transient failures.
466- Reusable policy helpers as semantic names for complex callbacks/configs.
467- AppForm, `ReactFormType` split sections, and field groups as separate composition tools.
468- Field vs `ArrayField`, especially array-as-immutable-value versus array-as-child-field-rendering-boundary.
469- Type-error debugging categories derived from the type tests.
470- Examples authoring as maintainer scaffolding for testing and future reference examples.
471- Standard Schema libraries as heuristic examples, with pipeline-vs-firewall/ruleset clearly marked as TanStack Form guidance rather than a Standard Schema concept.
472β
473Reviewed acceptance criteria:
474β
475- Skills never make `@tanstack/form-core` the user-facing workflow entrypoint.
476- Skills explain schemas through adapter APIs while preserving core semantics.
477- Skills distinguish validation errors from transient async failures.
478- Skills do not promise schema metadata extraction.
479- Skills do not use devtools or migration as current entrypoints.
480- Examples guidance is realistic enough for agents to build non-barren examples.