Open History to see the last commit
1schema_version: 1
2status: reviewed
3review_state: phase_5_finalized
4generated_from:
5 command: pnpm intent:scaffold
6 workflow: '@tanstack/intent domain-discovery'
7 phase: 5
8repository:
9 root: /home/luca/repos/tanstack/form-v2
10 package_manager: pnpm@11.8.0
11 monorepo: true
12 workspace_sources:
13 - package.json
14 - pnpm-workspace.yaml
15 - packages/*/package.json
16 - docs/**/*.md
17 - packages/*/src/**/*.ts
18 - packages/*/tests/**/*.ts
19 - packages/*/tests/**/*.tsx
20 - examples/react/**/*.tsx
21maintainer_guidance:
22 adapter_first: true
23 primary_user_entrypoint: '@tanstack/react-form'
24 secondary_user_entrypoint: '@tanstack/solid-form'
25 core_role: 'Concept and implementation source, not a user workflow entrypoint.'
26 primary_adapter_status:
27 react: 'Most complete adapter; use as primary examples and skill target.'
28 solid: 'Important adapter but missing critical planned pieces; avoid Solid-first coverage for now.'
29 schema_modes:
30 default_form_options:
31 summary: 'DefaultValues-first inference.'
32 use_when:
33 - 'The form type should be inferred from defaultValues.'
34 - 'Validation is mostly callback-based and callbacks should receive a value type derived from defaultValues.'
35 properties:
36 - 'defaultValues is taken at face value.'
37 - 'The inferred defaultValues type is used for validators and callbacks.'
38 - 'This mode is often the simplest choice when no schema should own the form type.'
39 strict_schema:
40 summary: 'Schema-source pipeline mode.'
41 use_when:
42 - 'The schema is a transforming pipeline from input type to output type.'
43 - 'The schema should be the source for form typing.'
44 properties:
45 - 'defaultValues must align with the schema input type and should produce type errors when they do not.'
46 - 'Callbacks may not have useful inference unless a schema is present in the validator array.'
47 - 'onSubmit should read the transform output from schemaOutputs instead of raw value.'
48 loose_schema:
49 summary: 'Schema-source ruleset mode with editable defaults.'
50 use_when:
51 - 'The schema is a ruleset for confirming valid output, but the editable form state needs nullable or undefined starting values.'
52 - 'A schema such as z.date() needs a starting value like null before the user has chosen a date.'
53 properties:
54 - 'The input is looser while the parsed submit output is still the schema output type.'
55 - 'defaultValues must still align with the schema shape, but properties may also be null or undefined where editing requires it.'
56 - 'Callbacks may not have useful inference unless a schema is present in the validator array.'
57 - 'onSubmit should read the transform output from schemaOutputs instead of raw value.'
58 schema_ecosystem:
59 standard_schema:
60 role: 'Most common integration shape.'
61 note: 'Standard Schema is an interoperability interface, not a pipeline-vs-ruleset classification system.'
62 source: 'https://standardschema.dev/'
63 pipeline_vs_ruleset_heuristic:
64 status: 'maintainer commentary'
65 meaning: 'A mental model for deciding TanStack Form option mode: is the schema written as a pipeline of constraints/transforms, or as a firewall that only lets already-valid values through?'
66 caution: 'This is not part of Standard Schema and should not be presented as a Standard Schema concept.'
67 validation_libraries_as_of_2026_06_25:
68 - name: Zod
69 standard_schema_support: 'Supported; Zod docs recommend Standard Schema for schema-agnostic black-box validation and say Zod is included among compatible libraries.'
70 general_leaning: 'ruleset/firewall-leaning by default'
71 tanstack_form_bias: 'Often looseSchema for editable forms, with strictSchema only when a Zod schema is deliberately authored as a transform pipeline.'
72 source: 'https://zod.dev/library-authors'
73 - name: Valibot
74 standard_schema_support: 'Implements Standard Schema v1.'
75 general_leaning: 'pipeline-leaning'
76 tanstack_form_bias: 'Often strictSchema when the schema is authored as an input-to-output pipeline.'
77 source: 'https://valibot.dev/guides/integrate-valibot/'
78 - name: ArkType
79 standard_schema_support: 'Supports and co-authored Standard Schema; can consume Standard Schema validators as definitions.'
80 general_leaning: 'mixed; structural firewall constraints with morph/pipe support for pipeline-style transforms'
81 tanstack_form_bias: 'Choose by the actual schema intent rather than the library name.'
82 source: 'https://arktype.io/docs/integrations'
83 - name: Effect Schema
84 standard_schema_support: 'Can generate Standard Schema V1 via Schema.standardSchemaV1 for schemas without dependencies.'
85 general_leaning: 'pipeline/codec-leaning because schemas distinguish decoded Type from Encoded input and support decoding/encoding.'
86 tanstack_form_bias: 'Often strictSchema when the Effect schema is used as an encoded-to-decoded boundary.'
87 source: 'https://effect.website/docs/schema/standard-schema/'
88 query_shape:
89 async_defaults: 'Incoming values are often maybe undefined while data loads.'
90 default_values_plan: 'Do not pass query data alone as form defaults; either gate mounted fields/form until data is ready, or coalesce query data with a static shape-complete emptyFormValues object. Neither strategy is preferred globally.'
91 visual_language: 'Gating fields or the whole form changes the visual UI language because the form appears only after data is ready; an emptyFormValues fallback can render the form immediately with loading or placeholder state.'
92 submit: 'Use an async promise for endpoint calls so isSubmitting reflects the request. Catch submit errors only when they can produce validation errors that must be returned as values. Transient thrown/rejected errors may remain thrown; they set isSubmitSuccessful to false while external query/framework state preserves the error.'
93 hard_do_nots:
94 - id: no_type_assertions
95 rule: 'Do not type assert to make TanStack Form code compile; preserve inference and fix the mismatched API boundary.'
96 bad_patterns:
97 - 'name={`users[${index}].name` as const}'
98 - '{(field: any) => ...}'
99 - 'field: { value: string }'
100 preferred_patterns:
101 - 'Let field names infer without as const.'
102 - 'Let form.Field render-prop children infer their field type.'
103 - 'Use FieldWithValue<T> or AnyFieldApi when a reusable component needs an explicit field prop type.'
104 - id: validation_errors_are_not_transient_errors
105 rule: 'Do not store query, network, or framework transient failures as form validation errors.'
106 reason: 'Validation errors from validators or onSubmit block the user from submitting; transient errors should use the query or framework error state.'
107 preferred_patterns:
108 - 'Use an async promise for endpoint calls so isSubmitting reflects the request.'
109 - 'Return createValidationError or parseIssues only for validation-shaped server responses.'
110 - 'Keep retryable network/server failures in the query or framework layer; they may throw or reject as transient failures.'
111 - id: validation_errors_are_values
112 rule: 'Do not throw validation errors from validators or onSubmit.'
113 reason: 'Validation errors must be returned values. Thrown/rejected errors are submit failures, not validation state.'
114 preferred_patterns:
115 - 'Return createValidationError(...) from onSubmit for validation failures.'
116 - 'Return parseIssues(...) when converting Standard Schema issues.'
117 - 'Let transient endpoint failures reject if the surrounding query/framework preserves the error state.'
118 - id: no_react_form_type_unions
119 rule: 'Do not type shared sections as unions of multiple ReactFormType forms.'
120 bad_patterns:
121 - 'form: ReactFormType<typeof formAOptions> | ReactFormType<typeof formBOptions>'
122 reason: 'TypeScript cannot make useful sense of different form API unions for field names and methods.'
123 preferred_patterns:
124 - 'Use ReactFormType<typeof sharedOptions> for splitting one known form into sections.'
125 - 'Use field groups when a reusable section should bind into multiple different forms or paths.'
126 excluded_from_current_skills:
127 - devtools_as_entrypoint
128 - migration_guidance
129 - schema_metadata_extraction
130 - non_validation_error_state_ownership
131 - ui_library_behavior_itself
132 - solid_first_examples
133domain_boundaries:
134 in_scope:
135 - 'React adapter-first form setup.'
136 - 'Core concepts explained through adapter APIs.'
137 - 'Standard Schema-compatible validation and submit parsing.'
138 - 'Choosing default, strictSchema, and looseSchema option modes.'
139 - 'Async default values and async submit with query-like libraries.'
140 - 'Error visibility policy callbacks.'
141 - 'Reusable split-form types and reusable validation or visibility policy modules.'
142 - 'Interpreting TypeScript errors caused by form/schema composition.'
143 - 'Authoring realistic examples that demonstrate intended usage.'
144 out_of_scope:
145 - 'Using @tanstack/form-core directly in app examples.'
146 - 'Devtools workflows while devtools are still changing.'
147 - 'Migration from v1 or other form libraries.'
148 - 'Deriving UI metadata from Standard Schemas.'
149 - 'Owning transient server/network error state inside TanStack Form.'
150 - 'Teaching a specific UI library as part of TanStack Form itself.'
151packages:
152 - name: '@tanstack/form-core'
153 role: concept_source
154 public_user_entrypoint: false
155 relevant_concepts:
156 - form_options
157 - strict_schema
158 - loose_schema
159 - standard_schema_parsing
160 - validation_errors
161 - error_visibility
162 - create_error_visibility
163 - create_validator
164 - create_validators
165 - async_defaults
166 - array_helpers
167 - array_field_versioning
168 - reset_semantics
169 sources:
170 - packages/form-core/src/utils.public.ts
171 - packages/form-core/src/validation.public.ts
172 - packages/form-core/src/standardSchema.public.ts
173 - packages/form-core/src/standardSchema.lib.ts
174 - packages/form-core/src/FormApi/FormApi.public.ts
175 - packages/form-core/src/FormApi/FormApi.lib.ts
176 - packages/form-core/src/FormApi/array-methods.lib.ts
177 - packages/form-core/src/FieldApi/fieldState.lib.ts
178 - packages/form-core/tests/validation.test.ts
179 - packages/form-core/tests/validation.test-d.ts
180 - packages/form-core/tests/FormApi/default-value.spec.ts
181 - packages/form-core/tests/FormApi/submission-handling.spec.ts
182 - packages/form-core/tests/FormApi/field-array-methods.spec.ts
183 - name: '@tanstack/react-form'
184 role: primary_user_entrypoint
185 public_user_entrypoint: true
186 relevant_concepts:
187 - use_form
188 - form_field
189 - array_field
190 - form_subscribe
191 - app_form
192 - app_form_options
193 - create_form_hook
194 - field_groups
195 - field_subscription
196 - array_field_subscription
197 - react_form_type
198 - field_with_value
199 - any_field_api
200 sources:
201 - packages/react-form/src/ReactForm/useForm.public.ts
202 - packages/react-form/src/ReactForm/ReactFormApi.lib.tsx
203 - packages/react-form/src/ReactForm/Components.public.ts
204 - packages/react-form/src/ReactForm/fieldSubscriptions.lib.ts
205 - packages/react-form/src/ReactForm/useField.lib.ts
206 - packages/react-form/src/AppForm/appFormOptions.public.ts
207 - packages/react-form/src/AppForm/createFormHook.public.ts
208 - packages/react-form/src/AppForm/getFormHookHelpers.public.ts
209 - packages/react-form/src/FieldGroup/withFields.public.ts
210 - packages/react-form/src/ReactForm/formType.public.ts
211 - packages/react-form/tests/useForm.spec.tsx
212 - packages/react-form/tests/submit-return.test-d.tsx
213 - packages/react-form/tests/FormGroup.test-d.tsx
214 - packages/react-form/tests/FieldGroupApi.test-d.tsx
215 - name: '@tanstack/solid-form'
216 role: secondary_adapter
217 public_user_entrypoint: true
218 current_skill_status: deferred
219 note: 'Use as conceptual parity context only until planned Solid adapter pieces land.'
220 - name: '@tanstack/form-devtools'
221 role: devtools
222 public_user_entrypoint: false
223 current_skill_status: excluded
224 note: 'Devtools are in development and should not be treated as an entrypoint yet.'
225domains:
226 - id: react-adapter-composition
227 title: React Adapter Composition
228 description: 'How users compose headless React forms, reusable field components, app form contexts, field groups, arrays, and UI-library bindings through @tanstack/react-form.'
229 package_focus:
230 - '@tanstack/react-form'
231 - '@tanstack/form-core'
232 core_questions:
233 - 'Should this be a one-off useForm example, an app-form setup, or a field-group composition?'
234 - 'Which pieces need to be reusable without over-constraining submit types?'
235 - 'Is this reducing nesting in one known form, reducing field JSX boilerplate, or reusing a section across forms?'
236 - 'Should split child components receive a form prop typed with ReactFormType derived from shared options, or should the section be a field group?'
237 - 'Does the example need field arrays or reorder behavior?'
238 related_skills:
239 - react-form-composition-setup
240 - examples-authoring
241 - type-error-debugging
242 - id: schema-driven-forms
243 title: Schema Driven Forms
244 description: 'How Standard Schema-compatible schemas influence form option mode, validation, field error routing, submit output, and TypeScript inference.'
245 package_focus:
246 - '@tanstack/react-form'
247 - '@tanstack/form-core'
248 core_questions:
249 - 'Is the schema a pipeline from input A to output B, or a ruleset for confirming B?'
250 - 'Should submit logic read raw value or schemaOutputs?'
251 - 'Do defaults need to be nullable or maybe undefined while editing?'
252 related_skills:
253 - choosing-form-options-modes
254 - schema-driven-forms
255 - type-error-debugging
256 - id: async-data-and-submit
257 title: Async Data And Submit
258 description: 'How query-like loading data and mutation-like submit functions interact with default values, touched fields, validation errors, and transient errors.'
259 package_focus:
260 - '@tanstack/react-form'
261 - '@tanstack/form-core'
262 core_questions:
263 - 'Can incoming data be undefined at first render?'
264 - 'Should later defaultValues update untouched fields while preserving touched fields?'
265 - 'Is an onSubmit failure transient or validation-related?'
266 related_skills:
267 - query-backed-forms
268 - error-visibility-workflows
269 - examples-authoring
270 - id: validation-and-error-visibility
271 title: Validation And Error Visibility
272 description: 'How validators produce errors, how Standard Schema issues are routed, and how visible errors are filtered by form-level or field-level callbacks.'
273 package_focus:
274 - '@tanstack/react-form'
275 - '@tanstack/form-core'
276 core_questions:
277 - 'When should an error become visible?'
278 - 'Should the visibility policy or validator trigger policy be extracted into a named reusable helper?'
279 - 'Is visibility form-wide, field-specific, or group-scoped?'
280 - 'Should submit errors be parsed from Standard Schema issues or manually created?'
281 related_skills:
282 - error-visibility-workflows
283 - schema-driven-forms
284 - query-backed-forms
285 - id: diagnostics-and-examples
286 title: Diagnostics And Examples
287 description: "How to turn the library's type surface and examples into agent-readable, realistic user journeys."
288 package_focus:
289 - '@tanstack/react-form'
290 - '@tanstack/form-core'
291 core_questions:
292 - 'What type boundary is producing the error?'
293 - 'Is the example demonstrating intended usage rather than only core behavior?'
294 - 'Which realistic integration should the example model without claiming ownership of external UI or query state?'
295 related_skills:
296 - type-error-debugging
297 - examples-authoring
298skill_candidates:
299 - id: react-form-composition-setup
300 title: React Form Composition Setup
301 status: reviewed
302 priority: high
303 domain: react-adapter-composition
304 purpose: 'Help users build adapter-first React forms, reusable components, app-form setups, field groups, and UI-library bindings.'
305 entrypoints:
306 - '@tanstack/react-form/useForm'
307 - '@tanstack/react-form/ReactFormType'
308 - '@tanstack/react-form/FieldWithValue'
309 - '@tanstack/react-form/AnyFieldApi'
310 - '@tanstack/react-form/formOptions'
311 - '@tanstack/react-form/createFormHook'
312 - 'form.Field'
313 - 'form.ArrayField'
314 - 'form.Subscribe'
315 - 'form.FormGroup'
316 sources:
317 - packages/react-form/src/ReactForm/Components.public.ts
318 - packages/react-form/src/ReactForm/fieldSubscriptions.lib.ts
319 - packages/react-form/src/AppForm/createFormHook.public.ts
320 - packages/react-form/src/FieldGroup/withFields.public.ts
321 - packages/react-form/tests/submit-return.test-d.tsx
322 - packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts
323 - packages/form-core/src/FieldApi/fieldState.lib.ts
324 - examples/react/array/src/index.tsx
325 - examples/react/basic-splitting-form/src/index.tsx
326 - examples/react/ui-integration-shadcn/src/components/form/app-form.ts
327 teaches:
328 - 'Prefer adapter APIs over constructing core APIs directly.'
329 - 'Use render-prop field APIs and subscriptions instead of copying form state into component state.'
330 - 'Treat useForm and useAppForm as stable form creation hooks, not reactive state reads.'
331 - 'Use useSelector or form.Subscribe when component output must react to form state.'
332 - 'Keep reusable shared options submit-agnostic when child components should accept multiple submit implementations.'
333 - 'Use ReactFormType<typeof sharedOptions> as one option for splitting a known form into child components that receive a form prop.'
334 - 'Do not union multiple ReactFormType forms for shared sections; use field groups when a section must bind into multiple different forms or paths.'
335 - 'Use AppForm to reduce repeated field JSX boilerplate; use split form sections to reduce component nesting; use field groups for reusable sections across forms or paths.'
336 - 'Let field names and form.Field children infer; use FieldWithValue<T> or AnyFieldApi for explicit reusable field component props.'
337 - 'form.Field may bind an array value; it behaves immutably like other fields, so any element change changes the array value and rerenders whole-array consumers.'
338 - 'Use form.ArrayField when an array is a rendering boundary for child fields or list items; ArrayField subscriptions follow array shape/version changes instead of treating value as the whole render unit.'
339 - 'Use field groups for reusable sections with virtual-to-real field bindings.'
340 failure_modes:
341 - name: type_asserting_form_inference
342 symptom: 'Code adds as const to field names, annotates render-prop children as any, or uses as any to force form code to compile.'
343 correction: 'Remove the assertion and let names, children, and form helpers infer the types.'
344 evidence:
345 - maintainer_guidance.hard_do_nots
346 - packages/react-form/src/ReactForm/Components.public.ts
347 - name: shimmed_field_prop_type
348 symptom: 'A reusable component accepts a hand-written field shape like field: { value: string }.'
349 correction: 'Use inferred render-prop types, FieldWithValue<T>, or AnyFieldApi instead of a structural shim.'
350 evidence:
351 - examples/react/basic-splitting-form/src/StringField.tsx
352 - examples/react/basic-splitting-form/src/FieldError.tsx
353 - name: expecting_hook_reactivity
354 symptom: 'A component reads form.state or derived flags from the stable useForm/useAppForm return and does not re-render when form state changes.'
355 correction: 'Use useSelector with form.atom or a field/group atom, or use form.Subscribe with an explicit selector.'
356 evidence:
357 - packages/react-form/src/ReactForm/ReactFormApi.lib.tsx
358 - packages/react-form/src/Subscribe.public.tsx
359 - packages/react-form/src/ReactForm/fieldSubscriptions.lib.ts
360 - examples/react/ui-integration-dnd-kit/src/twoLists/index.tsx
361 - name: core_as_user_entrypoint
362 symptom: 'Example imports @tanstack/form-core or constructs FormApi in React application code.'
363 correction: 'Use @tanstack/react-form APIs; treat core as concept and implementation source.'
364 evidence:
365 - maintainer_guidance.core_role
366 - packages/react-form/src/ReactForm/useForm.public.ts
367 - name: app_components_outside_provider
368 symptom: 'App field or form components throw because they are rendered outside form.Field or form.AppForm.'
369 correction: 'Wrap custom form components in the app-form provider pattern created by createFormHook.'
370 evidence:
371 - packages/react-form/src/AppForm/contexts.lib.ts
372 - examples/react/ui-integration-shadcn/src/components/form/app-form.ts
373 - name: over_specific_shared_form_type
374 symptom: 'A reusable child form prop rejects a parent form once onSubmit is added.'
375 correction: 'Keep shared options without onSubmit when reusable children should stay submit-agnostic.'
376 evidence:
377 - packages/react-form/src/ReactForm/formType.public.ts
378 - packages/react-form/tests/submit-return.test-d.tsx
379 - name: split_form_without_react_form_type
380 symptom: 'A split form section hand-writes a large form prop type or loses field-name inference.'
381 correction: 'Export shared form options and type the prop as ReactFormType<typeof sharedFormOptions>.'
382 evidence:
383 - examples/react/basic-splitting-form/src/FormSection.tsx
384 - docs/framework/react/reference/type-aliases/ReactFormType.md
385 - name: react_form_type_union_shared_section
386 symptom: 'A shared section accepts a union like ReactFormType<typeof formAOptions> | ReactFormType<typeof formBOptions> and TypeScript cannot resolve field names or methods.'
387 correction: 'Use field groups for reusable sections across forms, or use ReactFormType only for one known shared options type.'
388 evidence:
389 - maintainer_guidance.hard_do_nots
390 - packages/react-form/src/FieldGroup/withFields.public.ts
391 - name: field_used_for_rendering_array_children
392 symptom: 'A Field bound to an array value is used as the boundary for rendering item fields, and item updates rerender the whole array-value consumer.'
393 correction: 'Use ArrayField at the list boundary, then render item Fields for the values that should update independently.'
394 evidence:
395 - examples/react/array/src/index.tsx
396 - packages/react-form/src/ReactForm/fieldSubscriptions.lib.ts
397 - packages/form-core/src/FieldApi/fieldState.lib.ts
398 - name: array_field_assumed_required_for_any_array_value
399 symptom: 'Code reaches for ArrayField only because the field value is an array, even though the array is consumed as one immutable value.'
400 correction: 'Use Field when the array is a single field value; reserve ArrayField for rendering child fields or list items.'
401 evidence:
402 - packages/react-form/src/ReactForm/Components.public.ts
403 - packages/react-form/src/ReactForm/fieldSubscriptions.lib.ts
404 - name: raw_array_mutation
405 symptom: 'Array item values and field meta fall out of sync after splice, reorder, or manual setFieldValue.'
406 correction: 'Use pushFieldValue, insertFieldValue, removeFieldValue, swapFieldValues, moveFieldValue, clearFieldValues, or filterFieldValues.'
407 evidence:
408 - packages/form-core/src/FormApi/array-methods.lib.ts
409 - packages/form-core/src/FormApi/FormApiArrayMethods.types.public.ts
410 - packages/form-core/tests/FormApi/field-array-methods.spec.ts
411 - id: reusable-form-policies
412 title: Reusable Form Policies
413 status: reviewed
414 priority: high
415 domain: validation-and-error-visibility
416 purpose: 'Help users extract split-form types, error visibility callbacks, and validator configs into named reusable helpers when the behavior deserves semantic intent.'
417 entrypoints:
418 - '@tanstack/react-form/ReactFormType'
419 - 'createErrorVisibility'
420 - 'createValidator'
421 - 'createValidators'
422 - 'shared formOptions'
423 - 'shared appFormOptions'
424 sources:
425 - examples/react/basic-splitting-form/src/FormSection.tsx
426 - examples/react/basic-splitting-form/src/sharedForm.ts
427 - packages/react-form/tests/submit-return.test-d.tsx
428 - packages/form-core/tests/validation.test.ts
429 - packages/form-core/tests/validation.test-d.ts
430 - examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
431 teaches:
432 - 'Use ReactFormType<typeof sharedOptions> as the helper type for split form sections that receive a form prop.'
433 - 'ReactFormType splitting reduces nesting in one known form; AppForm reduces repeated field JSX; field groups cover sections reused across different forms or paths.'
434 - 'Prefer form-level errorVisibility callbacks over repeated local showErrors checks.'
435 - 'Use helper functions when a callback or validator config deserves a semantic name that preserves intent.'
436 - 'Use comments or JSDoc on named helpers to explain workflow behavior, trigger timing, debounce, bailIfInvalid, runOnSubmit, or rewardEarlyPunishLate policy.'
437 - 'Keep reusable visibility policies value-agnostic unless they are intentionally tied to one form shape; use inline callbacks when typed values are required.'
438 failure_modes:
439 - name: split_form_type_written_by_hand
440 symptom: 'A split form section loses field-name inference because its form prop type is hand-written.'
441 correction: 'Export shared options and type the prop as ReactFormType<typeof sharedOptions>.'
442 evidence:
443 - examples/react/basic-splitting-form/src/FormSection.tsx
444 - packages/react-form/tests/submit-return.test-d.tsx
445 - name: reusable_section_uses_react_form_type_union
446 symptom: 'A shared section accepts FormA | FormB and TypeScript cannot narrow field names or methods.'
447 correction: 'Use field groups for shared sections that need to work across different forms or paths.'
448 evidence:
449 - maintainer_guidance.hard_do_nots
450 - packages/react-form/src/FieldGroup/withFields.public.ts
451 - name: scattered_show_errors_policy
452 symptom: 'Each field repeats local showErrors logic such as field.meta.isTouched && field.meta.isInvalid.'
453 correction: 'Move default visible-error behavior into form-level errorVisibility, or extract a named createErrorVisibility helper.'
454 evidence:
455 - packages/form-core/tests/validation.test-d.ts
456 - examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
457 - name: duplicated_validator_config_without_intent
458 symptom: 'Trigger, debounce, runOnSubmit, or bailIfInvalid config is copied without explaining the intended workflow.'
459 correction: 'Extract a named createValidator/createValidators helper and document the behavior intent.'
460 evidence:
461 - packages/form-core/tests/validation.test.ts
462 - examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
463 - name: reusable_visibility_reads_concrete_values
464 symptom: 'A reusable createErrorVisibility callback tries to read a concrete property such as state.values.name.'
465 correction: 'Keep reusable policies value-agnostic, or use an inline errorVisibility callback when concrete typed values are needed.'
466 evidence:
467 - packages/form-core/tests/validation.test-d.ts
468 - id: choosing-form-options-modes
469 title: Choosing Form Options Modes
470 status: reviewed
471 priority: high
472 domain: schema-driven-forms
473 purpose: 'Help users choose default formOptions, strictSchema, or looseSchema based on whether the schema is a transform pipeline or a validation ruleset.'
474 entrypoints:
475 - '@tanstack/react-form/formOptions'
476 - '@tanstack/react-form/formOptions.strictSchema'
477 - '@tanstack/react-form/formOptions.looseSchema'
478 - '@tanstack/react-form/appFormOptions'
479 - '@tanstack/react-form/appFormOptions.strictSchema'
480 - '@tanstack/react-form/appFormOptions.looseSchema'
481 sources:
482 - packages/form-core/src/utils.public.ts
483 - packages/react-form/src/AppForm/appFormOptions.public.ts
484 - packages/form-core/tests/validation.test.ts
485 - packages/form-core/tests/validation.test-d.ts
486 - examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
487 teaches:
488 - 'The option helpers are runtime identity helpers with type-level meaning.'
489 - 'Default formOptions infers from defaultValues; those values are taken at face value and drive validator callback value types.'
490 - 'strictSchema uses the schema as the typing source for a transforming input-to-output pipeline.'
491 - 'strictSchema defaultValues must align with the schema input type and should fail type-checking when they do not.'
492 - 'looseSchema uses the schema as a ruleset while allowing editable default values that include null or undefined where needed.'
493 - 'looseSchema defaultValues must still align with the schema shape, but the input can be looser while output remains schema output.'
494 - 'In schema modes, callbacks may not infer usefully unless a schema is present in the validator array.'
495 - 'In schema modes, onSubmit should read schemaOutputs instead of raw value.'
496 - 'Use Standard Schema-capable libraries as heuristic examples only: Zod generally leans ruleset/firewall, Valibot generally leans pipeline, ArkType is mixed, and Effect Schema often leans pipeline/codec.'
497 failure_modes:
498 - name: expecting_option_helper_runtime_behavior
499 symptom: 'User expects strictSchema or looseSchema to add validation without validators.'
500 correction: 'Explain that the helper shapes inference; validation still comes from configured validators.'
501 evidence:
502 - packages/form-core/src/utils.public.ts
503 - packages/form-core/tests/validation.test.ts
504 - name: schema_expected_to_type_default_form_options
505 symptom: 'User chooses default formOptions but expects a schema to own the form data type.'
506 correction: 'Use default formOptions for defaultValues-first inference, or choose a schema mode when the schema should be the typing source.'
507 evidence:
508 - maintainer_guidance.schema_modes
509 - packages/form-core/src/utils.public.ts
510 - name: strict_ruleset_schema_blocks_editing
511 symptom: 'Defaults or field values cannot represent empty, null, or partial UI states because strict schema typing is too narrow.'
512 correction: 'Use looseSchema or default formOptions when the schema is a ruleset validating final form shape.'
513 evidence:
514 - maintainer_guidance.schema_modes
515 - packages/form-core/src/utils.public.ts
516 - name: loose_schema_shape_mismatch
517 symptom: "Loose schema defaults include null or undefined but no longer match the schema's object shape or field structure."
518 correction: 'Keep the defaultValues shape aligned with the schema while allowing null or undefined where editable state needs it.'
519 evidence:
520 - maintainer_guidance.schema_modes
521 - packages/form-core/src/utils.public.ts
522 - name: schema_mode_without_schema_validator
523 symptom: 'Callbacks in strictSchema or looseSchema mode do not infer the expected value type.'
524 correction: 'Put a schema in the validator array so the helper has a schema source to infer from.'
525 evidence:
526 - maintainer_guidance.schema_modes
527 - packages/form-core/tests/validation.test-d.ts
528 - name: loose_pipeline_schema_loses_transform_intent
529 symptom: 'Submit logic treats raw form value as if it were the transformed schema output.'
530 correction: 'Use strictSchema for pipeline schemas and read the transformed value from schemaOutputs.'
531 evidence:
532 - packages/form-core/tests/validation.test.ts
533 - packages/form-core/tests/validation.test-d.ts
534 - name: on_submit_reads_value_in_schema_mode
535 symptom: 'onSubmit reads value even though strictSchema or looseSchema is being used.'
536 correction: 'Read the relevant schemaOutputs entry, because both schema modes preserve raw form value separately from parsed output.'
537 evidence:
538 - packages/form-core/tests/validation.test.ts
539 - packages/form-core/src/FormApi/FormApi.public.ts
540 - name: confusing_zod_input_with_pipeline_input
541 symptom: 'A Zod schema is treated as a reliable A-to-B pipeline because z.input differs from z.output.'
542 correction: 'Start from Zod-as-ruleset guidance unless the specific schema is deliberately written as a transform pipeline.'
543 evidence:
544 - maintainer_guidance.schema_ecosystem
545 - examples/react/ui-integration-shadcn/src/app/booking/schema.ts
546 - id: schema-driven-forms
547 title: Schema Driven Forms
548 status: reviewed
549 priority: high
550 domain: schema-driven-forms
551 purpose: 'Help users turn Standard Schema-compatible schemas into form validators, field errors, typed submit output, and realistic examples.'
552 entrypoints:
553 - 'validators'
554 - 'schemaOutputs'
555 - 'parseIssues'
556 - 'createValidationError'
557 - 'Standard Schema validators'
558 sources:
559 - packages/form-core/src/standardSchema.public.ts
560 - packages/form-core/src/standardSchema.lib.ts
561 - packages/form-core/src/FormApi/FormApi.public.ts
562 - packages/form-core/tests/validation.test.ts
563 - packages/form-core/tests/validation.test-d.ts
564 - examples/react/ui-integration-shadcn/src/app/booking/schema.ts
565 - examples/react/field-groups/src/index.tsx
566 teaches:
567 - 'Use Standard Schema-compatible validators in form or field validators.'
568 - 'Extract reusable validator trigger configs with createValidator or createValidators when the policy is complex enough to deserve a semantic name.'
569 - 'Read parsed schema output from onSubmit context.schemaOutputs.'
570 - 'Return validation errors as values through createValidationError or parseIssues; do not throw them.'
571 - 'Let Standard Schema issue paths route field errors instead of hand-building brittle path maps.'
572 failure_modes:
573 - name: assuming_schema_output_replaces_value
574 symptom: 'onSubmit reads value expecting transformed/coerced data.'
575 correction: 'Use schemaOutputs for parsed schema output; value remains form state.'
576 evidence:
577 - packages/form-core/src/FormApi/FormApi.public.ts
578 - packages/form-core/tests/validation.test.ts
579 - name: returning_raw_schema_error
580 symptom: 'A submit validator returns or throws raw Zod/Standard Schema errors and the form does not show intended field errors.'
581 correction: 'Return parseIssues for Standard Schema issues or createValidationError for explicit form/field errors; validation errors must be values, not thrown errors.'
582 evidence:
583 - packages/form-core/src/FormApi/FormApi.public.ts
584 - packages/form-core/tests/FormApi/submission-handling.spec.ts
585 - name: manual_path_mapping
586 symptom: 'Nested and array validation errors are routed to the wrong field names.'
587 correction: 'Use Standard Schema parsing so paths like user.name and users[0].name are produced consistently.'
588 evidence:
589 - packages/form-core/src/standardSchema.lib.ts
590 - packages/form-core/tests/validation.test.ts
591 - name: duplicated_validator_policy
592 symptom: 'The same triggers, debounce, runOnSubmit, or bailIfInvalid choices are copied across validators with no explanation.'
593 correction: 'Extract a named createValidator/createValidators helper when the policy has semantic meaning, and document why that behavior exists.'
594 evidence:
595 - packages/form-core/tests/validation.test.ts
596 - examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
597 - name: schema_metadata_expectation
598 symptom: 'Example tries to infer required labels, descriptions, or UI decorations from Standard Schema metadata.'
599 correction: 'Keep UI metadata explicit or schema-library-specific; Standard Schema does not standardize metadata.'
600 evidence:
601 - maintainer_guidance.excluded_from_current_skills
602 - id: query-backed-forms
603 title: Query Backed Forms
604 status: reviewed
605 priority: high
606 domain: async-data-and-submit
607 purpose: 'Help users combine forms with query-like async defaults and mutation-like submit calls while separating transient failures from validation errors.'
608 entrypoints:
609 - 'useForm defaultValues'
610 - 'onSubmit'
611 - 'form.reset'
612 - 'createValidationError'
613 - 'parseIssues'
614 sources:
615 - packages/react-form/tests/useForm.spec.tsx
616 - packages/form-core/src/FormApi/FormApi.lib.ts
617 - packages/form-core/src/FormApi/FormApi.public.ts
618 - packages/form-core/tests/FormApi/default-value.spec.ts
619 - packages/form-core/tests/FormApi/submission-handling.spec.ts
620 teaches:
621 - 'Maybe-undefined incoming data requires an explicit default-values plan, not direct query data alone.'
622 - 'Approach 1: gate the fields, or the whole form, until the query is ready so mounted fields start with correct data.'
623 - 'Approach 2: define a static shape-complete emptyFormValues object and pass defaultValues as queryData ?? emptyFormValues.'
624 - 'Neither approach is preferred globally; choose based on the desired loading and visual UI language.'
625 - 'Gating fields changes the UI because fields mount only after data is ready, while an emptyFormValues fallback can show the form immediately.'
626 - 'Let updated defaultValues populate untouched fields while preserving user-touched fields.'
627 - 'Use an async promise for endpoint calls inside onSubmit so isSubmitting reflects the request.'
628 - 'Catch submit errors only when the endpoint can return validation errors that should be converted into createValidationError or parseIssues values.'
629 - 'Transient submit errors can throw or reject; they set isSubmitSuccessful to false while query/framework state should preserve the error details.'
630 - 'Remember that errors stored from validators or onSubmit block submission, so transient errors should not be converted into validation errors.'
631 - 'Use reset semantics deliberately when replacing values and default baselines.'
632 failure_modes:
633 - name: undefined_data_as_final_shape
634 symptom: 'Initial query data is undefined, so fields or schema types collapse into invalid permanent defaults.'
635 correction: 'Either gate mounting until data is ready, or coalesce with a static shape-complete emptyFormValues object.'
636 evidence:
637 - packages/react-form/tests/useForm.spec.tsx
638 - maintainer_guidance.query_shape
639 - name: query_data_without_fallback_plan
640 symptom: 'defaultValues is fed directly from query.data even though query.data can be undefined.'
641 correction: 'Use query.data ?? emptyFormValues, or delay mounting fields/form until the query has populated data.'
642 evidence:
643 - maintainer_guidance.query_shape
644 - packages/react-form/tests/useForm.spec.tsx
645 - name: ignoring_loading_visual_language
646 symptom: 'An example gates fields without accounting for the different loading UI, or renders empty fallback values without communicating that data is still loading.'
647 correction: 'Choose the default-values plan together with the intended visual loading language.'
648 evidence:
649 - maintainer_guidance.query_shape
650 - name: overwriting_touched_fields
651 symptom: 'Late async defaults replace user edits.'
652 correction: "Use the form's defaultValues update behavior, which preserves touched fields and updates untouched fields."
653 evidence:
654 - packages/form-core/src/FormApi/FormApi.lib.ts
655 - packages/react-form/tests/useForm.spec.tsx
656 - name: transient_error_as_validation_error
657 symptom: 'Network/server outage becomes a visible field validation error.'
658 correction: 'Keep transient error state in the query or framework layer; return createValidationError or parseIssues only for validation failures, because stored validation errors block submission.'
659 evidence:
660 - packages/form-core/tests/FormApi/submission-handling.spec.ts
661 - maintainer_guidance.query_shape
662 - name: non_async_endpoint_call
663 symptom: 'onSubmit starts an endpoint call without returning or awaiting its promise, so isSubmitting does not cover the request.'
664 correction: 'Return or await the async endpoint promise from onSubmit.'
665 evidence:
666 - packages/form-core/tests/FormApi/submission-handling.spec.ts
667 - packages/form-core/src/FormApi/handleSubmit.lib.ts
668 - name: thrown_validation_error
669 symptom: 'onSubmit throws or rejects with validation information and expects field errors.'
670 correction: 'Convert validation failures into returned createValidationError or parseIssues values; thrown/rejected errors are submit failures.'
671 evidence:
672 - packages/form-core/tests/FormApi/submission-handling.spec.ts
673 - packages/form-core/src/FormApi/FormApi.public.ts
674 - name: rejected_submit_expected_to_show_field_errors
675 symptom: 'onSubmit throws or rejects a transient failure and the user expects field errors to appear.'
676 correction: 'Let transient failures remain transient and use query/framework error state; only validation failures should be converted into returned validation values.'
677 evidence:
678 - packages/form-core/tests/FormApi/submission-handling.spec.ts
679 - packages/form-core/src/FormApi/FormApi.public.ts
680 - id: error-visibility-workflows
681 title: Error Visibility Workflows
682 status: reviewed
683 priority: high
684 domain: validation-and-error-visibility
685 purpose: 'Help users implement visible-error policies such as show-after-blur, show-after-submit, or custom workflows.'
686 entrypoints:
687 - 'errorVisibility'
688 - 'createErrorVisibility'
689 - 'createValidator'
690 - 'createValidators'
691 - 'fieldState.meta'
692 - 'state.submissionAttempts'
693 - 'form.FormGroup'
694 sources:
695 - packages/form-core/src/validation.public.ts
696 - packages/form-core/src/FieldApi/fieldState.lib.ts
697 - packages/form-core/src/utils.public.ts
698 - packages/form-core/tests/validation.test-d.ts
699 - packages/form-core/tests/FormApi/validation.spec.ts
700 - packages/form-core/tests/FormGroupApi/FormGroupApi.spec.ts
701 - examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
702 teaches:
703 - 'errorVisibility is a callback, not a string preset.'
704 - 'Use form-level errorVisibility to control default visible-error behavior instead of scattering local checks like field.meta.isTouched && field.meta.isInvalid.'
705 - 'Reusable policies can use createErrorVisibility but only receive unknown form values.'
706 - 'Helper functions mainly serve to give a semantic name to a callback or validator config.'
707 - 'Named reusable policies are good places for JSDoc or comments that explain why errors appear at that moment.'
708 - 'Reusable validator configs are useful when they explain trigger timing, bailIfInvalid, debounce, runOnSubmit, or rewardEarlyPunishLate behavior.'
709 - 'Inline callbacks can use typed form values from the consuming form.'
710 - 'Visibility callbacks see pre-filter meta, not visible errors or validity.'
711 - 'Group submission attempts are scoped to the nearest group.'
712 failure_modes:
713 - name: string_preset
714 symptom: "User writes errorVisibility: 'touched' or errorVisibility: 'always'."
715 correction: 'Use a callback or createErrorVisibility helper.'
716 evidence:
717 - packages/form-core/tests/validation.test-d.ts
718 - packages/form-core/src/validation.public.ts
719 - name: scattered_local_error_display
720 symptom: 'Each field repeats local showErrors expressions like field.meta.isTouched && field.meta.isInvalid.'
721 correction: 'Move default visible-error behavior into form-level errorVisibility.'
722 evidence:
723 - maintainer_guidance
724 - examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
725 - name: checking_visible_errors_inside_visibility
726 symptom: 'Visibility callback tries to inspect fieldState.meta.errors or validity.'
727 correction: 'Base visibility on pre-filter meta such as isBlurred, isTouched, isDirty, or submissionAttempts.'
728 evidence:
729 - packages/form-core/tests/validation.test-d.ts
730 - packages/form-core/src/FieldApi/fieldState.lib.ts
731 - name: reusable_policy_expects_typed_values
732 symptom: 'A createErrorVisibility callback tries to read state.values.name with a concrete form type.'
733 correction: 'Use inline errorVisibility when typed values are required, or keep reusable policies value-agnostic.'
734 evidence:
735 - packages/form-core/tests/validation.test-d.ts
736 - name: undocumented_policy_intent
737 symptom: 'A complex visibility or validator trigger policy is copied inline, making agents preserve the code but miss the workflow intent.'
738 correction: 'Extract a named helper and use comments or JSDoc to document the intended user behavior.'
739 evidence:
740 - packages/form-core/tests/validation.test.ts
741 - examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
742 - name: group_submit_scope_surprise
743 symptom: 'A wizard section expects form-level submit attempts and group-level submit attempts to be interchangeable.'
744 correction: 'Account for nearest group scoping when using state.submissionAttempts in grouped forms.'
745 evidence:
746 - packages/form-core/tests/FormGroupApi/FormGroupApi.spec.ts
747 - id: type-error-debugging
748 title: Type Error Debugging
749 status: reviewed
750 priority: medium
751 domain: diagnostics-and-examples
752 purpose: 'Help users interpret large TypeScript errors from schemas, option modes, field groups, reusable forms, and adapter APIs.'
753 entrypoints:
754 - 'ReactFormType'
755 - 'FieldWithValue'
756 - 'AnyFieldApi'
757 - 'formOptions'
758 - 'appFormOptions'
759 - 'createErrorVisibility'
760 - 'createValidators'
761 - 'fieldComponent.strict'
762 - 'fieldComponent.loose'
763 - 'fieldBrand.strict'
764 - 'fieldBrand.loose'
765 - 'getFieldGroupHelpers'
766 - 'DeepKeys'
767 - 'DeepValue'
768 sources:
769 - packages/form-core/tests/validation.test-d.ts
770 - packages/form-core/tests/deep-keys.test-d.ts
771 - packages/react-form/tests/submit-return.test-d.tsx
772 - packages/react-form/tests/FormGroup.test-d.tsx
773 - packages/react-form/tests/FieldGroupApi.test-d.tsx
774 - packages/react-form/src/AppForm/getFormHookHelpers.public.ts
775 - packages/react-form/src/FieldGroup/withFields.public.ts
776 teaches:
777 - 'Do not use type assertions to silence TanStack Form type errors; preserve inference and fix the mismatched boundary.'
778 - 'Classify the error by boundary: option mode, schema output, submit return, reusable child form prop, error visibility state, validator helper arity, form group scope, field group virtual path or binding, field component brand, deep-key path, or public API surface.'
779 - 'Treat ReactFormType unions in shared sections as a composition issue; use field groups instead of asserting through the union.'
780 - 'Separate schema strict/loose from field component strict/loose; they solve different problems.'
781 - 'For long errors, find the first concrete path, value, validator, or submit-return mismatch and ignore expanded generic machinery around it.'
782 - 'Reusable createErrorVisibility callbacks are form-agnostic; unknown values usually mean the policy should stay generic or become an inline callback.'
783 - 'createValidators type errors usually mean the count of run functions does not match the count of option configs.'
784 - 'FormGroup type errors usually mean a root-form path or value was used where group-scoped paths or values are expected.'
785 - 'Field-group type errors usually mean real paths were used where virtual paths are expected, a binding map is incomplete, or strict/loose slot compatibility was chosen incorrectly.'
786 - 'Deep-key path errors usually point to path shape; arrays use bracket segments and array helpers only accept paths whose value includes an array.'
787 - 'Use the first meaningful generic mismatch instead of the full expanded error wall.'
788 - 'Check whether the code is trying to use private/internal shape rather than public atom-based APIs.'
789 failure_modes:
790 - name: assertion_hides_form_inference
791 symptom: 'A user adds as const, as any, or a render-prop annotation like field: any to make an error disappear.'
792 correction: 'Remove the assertion and follow the inferred API boundary; use FieldWithValue<T> or AnyFieldApi for reusable field props.'
793 evidence:
794 - maintainer_guidance.hard_do_nots
795 - examples/react/basic-splitting-form/src/StringField.tsx
796 - examples/react/basic-splitting-form/src/FieldError.tsx
797 - name: react_form_type_union
798 symptom: 'A shared section types its form prop as a union of multiple ReactFormType aliases.'
799 correction: 'Use field groups for shared sections across forms; ReactFormType is for splitting a known form.'
800 evidence:
801 - maintainer_guidance.hard_do_nots
802 - packages/react-form/src/FieldGroup/withFields.public.ts
803 - name: reusable_error_visibility_unknown_values
804 symptom: 'A createErrorVisibility helper tries to read a concrete property such as state.values.name.'
805 correction: 'Keep reusable policies value-agnostic, or use an inline callback when concrete form values are needed.'
806 evidence:
807 - packages/form-core/tests/validation.test-d.ts
808 - name: create_validators_arity_mismatch
809 symptom: 'createValidators reports a long tuple or overload error around missing or extra run functions.'
810 correction: 'Pass exactly one run function for each option config.'
811 evidence:
812 - packages/form-core/tests/validation.test-d.ts
813 - name: form_group_scope_mismatch
814 symptom: 'A FormGroup validator or field name complains about missing root fields or invalid paths.'
815 correction: 'Use group-scoped values and paths inside the group; reach through group.form only when root form state is intentionally needed.'
816 evidence:
817 - packages/react-form/tests/FormGroup.test-d.tsx
818 - name: field_group_virtual_path_mismatch
819 symptom: 'A field group method, watchFields entry, Field, or ArrayField rejects a real form path.'
820 correction: 'Use the virtual paths defined by defineFields inside the field group; map them to real paths only through withFields bindings.'
821 evidence:
822 - packages/react-form/tests/FieldGroupApi.test-d.tsx
823 - name: field_group_binding_map_mismatch
824 symptom: 'withFields rejects a binding map as incomplete, wrong, or as the internal defineFields object.'
825 correction: 'Provide every defined field binding, pass real form paths as bindings, and include the required form prop.'
826 evidence:
827 - packages/react-form/tests/FieldGroupApi.test-d.tsx
828 - name: deep_key_path_shape_mismatch
829 symptom: 'A field name or array helper rejects a path involving arrays, optional arrays, readonly arrays, or nullish data.'
830 correction: 'Check the DeepKeys path shape, including bracket array segments like users[0].name and array-valued path constraints.'
831 evidence:
832 - packages/form-core/tests/deep-keys.test-d.ts
833 - name: schema_strict_loose_vs_field_strict_loose
834 symptom: 'User assumes fieldComponent.strict/loose means strictSchema/looseSchema.'
835 correction: 'Explain schema option modes separately from field component value-compatibility branding.'
836 evidence:
837 - packages/react-form/src/AppForm/getFormHookHelpers.public.ts
838 - packages/form-core/src/utils.public.ts
839 - name: submit_specific_type_leaks_to_reusable_child
840 symptom: 'A reusable child rejects a form because TOnSubmit differs.'
841 correction: 'Use shared options without onSubmit or type the child around the intended ReactFormType boundary.'
842 evidence:
843 - packages/react-form/tests/submit-return.test-d.tsx
844 - name: strict_field_group_binding_mismatch
845 symptom: 'A field group strict slot rejects a real field path whose value is only assignable in one direction.'
846 correction: 'Use a loose field slot when the reusable group should accept wider compatible field values.'
847 evidence:
848 - packages/react-form/tests/FieldGroupApi.test-d.tsx
849 - packages/react-form/src/FieldGroup/withFields.public.ts
850 - name: public_api_store_confusion
851 symptom: 'Type error mentions missing store because example uses form.store or field.store.'
852 correction: 'Use public atom-based APIs and adapter subscriptions.'
853 evidence:
854 - packages/react-form/tests/FormGroup.test-d.tsx
855 - packages/react-form/src/ReactForm/fieldSubscriptions.lib.ts
856 - id: examples-authoring
857 title: Examples Authoring
858 status: reviewed
859 priority: high
860 domain: diagnostics-and-examples
861 purpose: 'Help Codex scaffold substantial maintainer examples for testing, future documentation, and user reference.'
862 entrypoints:
863 - 'examples/react/basic'
864 - 'examples/react/array'
865 - 'examples/react/basic-splitting-form'
866 - 'examples/react/field-groups'
867 - 'examples/react/ui-integration-shadcn'
868 - 'examples/react/ui-integration-dnd-kit'
869 sources:
870 - examples/react/basic/src/index.tsx
871 - examples/react/array/src/index.tsx
872 - examples/react/basic-splitting-form/src/index.tsx
873 - examples/react/field-groups/src/index.tsx
874 - examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx
875 - examples/react/ui-integration-shadcn/src/app/booking/booking-form.tsx
876 - examples/react/ui-integration-dnd-kit/src/singleList/index.tsx
877 - examples/react/ui-integration-dnd-kit/src/twoLists/index.tsx
878 teaches:
879 - 'Examples are scaffolding targets for maintainers in this private repository, and future users experience them as reference examples.'
880 - 'Examples should model user journeys, not just newly added core behavior.'
881 - 'Use React adapter APIs and realistic composition patterns.'
882 - 'When an example renders arrays of fields, use ArrayField at the list boundary and Field for item properties; when an array is one immutable value, Field is acceptable.'
883 - 'Show schema mode choice, async defaults, submit handling, and error visibility together when that reflects a real task.'
884 - 'Use useSelector or form.Subscribe for reactive form state reads; the form hook return is stable by design.'
885 - 'Keep UI library and query-library ownership boundaries honest.'
886 failure_modes:
887 - name: barren_core_test_example
888 symptom: 'Example only proves a core feature works and does not teach how a user should compose a real form.'
889 correction: 'Write examples around realistic adapter-first user journeys.'
890 evidence:
891 - maintainer_guidance.adapter_first
892 - examples/react/basic/src/index.tsx
893 - examples/react/ui-integration-shadcn/src/app/booking/booking-form.tsx
894 - name: dnd_multi_list_index_model
895 symptom: 'Multi-list drag-and-drop stores items as a single indexed array and races React with the DnD library.'
896 correction: 'Use stable item IDs with separate order arrays for cross-list movement.'
897 evidence:
898 - examples/react/ui-integration-dnd-kit/src/twoLists/index.tsx
899 - name: native_reset_surprise
900 symptom: 'A reset button triggers browser-native reset instead of form.reset semantics.'
901 correction: 'Prevent default button behavior and call form.reset intentionally.'
902 evidence:
903 - examples/react/basic/src/index.tsx
904 - packages/form-core/tests/FormApi/default-value.spec.ts
905 - name: submit_button_not_subscribed
906 symptom: 'Submit button does not reflect canSubmit or isSubmitting reliably.'
907 correction: 'Use form.Subscribe selectors for submit-related state.'
908 evidence:
909 - examples/react/basic/src/index.tsx
910 - packages/react-form/src/ReactForm/Components.public.ts
911gaps:
912 - id: missing-tanstack-query-example
913 skill: query-backed-forms
914 status: open
915 question: 'No checked-in query-backed example was available in this filesystem snapshot.'
916 context: 'The IDE referenced examples/react/tanstack-query/src/App.tsx, but examples/react/tanstack-query was absent. Query-backed guidance is therefore sourced from tests and maintainer interview until a realistic example is scaffolded.'
917evidence_constraints:
918 - id: docs-are-mostly-reference
919 status: noted
920 note: 'The docs directory is largely generated API reference; conceptual documentation is sparse.'
921 implication: 'Generated skills should lean on source, tests, examples, and maintainer interview for current intent.'
922 - id: no-private-issue-signal
923 status: resolved
924 note: 'Maintainer clarified private issues are developer TODOs/plans and not useful user-problem evidence.'
925 implication: 'Do not mine private issues for skill priorities in this repository.'
926 - id: examples-are-maintainer-scaffolds
927 status: resolved
928 note: "Examples are needed so maintainers can test scenarios and expand future documentation; intent skills should improve Codex's ability to scaffold them."
929 implication: 'Do not treat example selection as a public roadmap priority question. Future users primarily consume examples as references.'
930tensions:
931 - id: schema_strictness_vs_editable_defaults
932 skills:
933 - choosing-form-options-modes
934 - schema-driven-forms
935 - type-error-debugging
936 description: 'Schema-source typing improves parsed output confidence, but editable form defaults may need nullable or undefined intermediate values.'
937 implication: 'Agents may choose strictSchema for a ruleset-style form and then fight nullish defaults with assertions, or choose looseSchema for a true transform pipeline and read raw value.'
938 - id: query_loading_ui_vs_form_initialization
939 skills:
940 - query-backed-forms
941 - examples-authoring
942 description: 'Gating a form until query data arrives gives correct initial state, while fallback empty values let the UI render immediately.'
943 implication: 'Agents may pass maybe-undefined query data directly or choose a loading strategy without matching the visual workflow.'
944 - id: validation_state_vs_transient_state
945 skills:
946 - query-backed-forms
947 - schema-driven-forms
948 - error-visibility-workflows
949 description: 'Validation errors are form state that can block submission; transient query/network/framework failures belong outside validation state.'
950 implication: 'Agents may convert retryable endpoint failures into visible field errors and accidentally block the next submit.'
951 - id: reuse_vs_inference_boundaries
952 skills:
953 - react-form-composition-setup
954 - reusable-form-policies
955 - type-error-debugging
956 - examples-authoring
957 description: 'Reusable sections improve examples and app code, but the wrong abstraction boundary breaks inference.'
958 implication: 'Agents may assert field names, hand-write field props, or union ReactFormType forms instead of using inferred children, helper types, or field groups.'
959cross_references:
960 - from: react-form-composition-setup
961 to: examples-authoring
962 reason: 'Examples should model adapter-first composition choices instead of core-level API proofs.'
963 - from: react-form-composition-setup
964 to: reusable-form-policies
965 reason: 'Split sections, AppForm, and field groups determine which reusable helper type or policy boundary is appropriate.'
966 - from: reusable-form-policies
967 to: react-form-composition-setup
968 reason: 'Reusable policies should not replace the larger composition choice between split forms, AppForm, and field groups.'
969 - from: reusable-form-policies
970 to: error-visibility-workflows
971 reason: 'Named visibility helpers should preserve the user workflow that controls when errors appear.'
972 - from: reusable-form-policies
973 to: type-error-debugging
974 reason: 'Reusable helper boundaries often explain long ReactFormType, createErrorVisibility, and createValidators errors.'
975 - from: examples-authoring
976 to: react-form-composition-setup
977 reason: 'Example scaffolds need the Field, ArrayField, Subscribe, AppForm, ReactFormType, and field-group boundaries.'
978 - from: choosing-form-options-modes
979 to: schema-driven-forms
980 reason: 'Schema validation and submit output depend on the selected option mode.'
981 - from: choosing-form-options-modes
982 to: type-error-debugging
983 reason: 'Many large type errors originate at the default, strictSchema, or looseSchema boundary.'
984 - from: schema-driven-forms
985 to: query-backed-forms
986 reason: 'Query-backed submit handlers often need to convert server validation responses into returned validation values.'
987 - from: query-backed-forms
988 to: error-visibility-workflows
989 reason: 'Async defaults and submit failures often change when users expect validation errors to become visible.'
990 - from: type-error-debugging
991 to: react-form-composition-setup
992 reason: 'Most type fixes should preserve adapter inference instead of adding assertions.'
993phase5_finalization:
994 reviewed_on: '2026-06-25'
995 resolved_interview_topics:
996 - hard_do_nots
997 - schema_mode_wording
998 - query_backed_default_value_strategies
999 - async_on_submit_errors
1000 - reusable_policy_helpers
1001 - app_form_vs_split_sections_vs_field_groups
1002 - field_vs_array_field
1003 - type_error_debugging_from_type_tests
1004 - examples_as_maintainer_scaffolds
1005 - standard_schema_libraries_as_heuristic_examples
1006 remaining_open_gaps:
1007 - missing-tanstack-query-example