[v2] Feat: Add Default options for React App Forms (#2336)

* feat: add default options to app form

* docs: add JSDoc to react form composition

* chore: generate docs and fix coderabbit

* fix: remove nonsense type prop pick

* chore: apply suggestions from coderabbit

* chore: add istanbul coverage for adapters

Author: LeCarbonator

.changeset/gentle-forms-default.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/react-form': minor
+---
+
+Add default form, field, and form group options to `createFormHook`.

.coderabbit.yaml

@@ -3,3 +3,6 @@ reviews:
     base_branches:
       - alpha
       - main
+  path_filters:
+    - '!docs/reference/**'
+    - '!docs/framework/*/reference/**'

docs/config.json

@@ -357,6 +357,59 @@
         }
       ]
     },
+    {
+      "label": "Form Composition API Reference",
+      "collapsible": true,
+      "defaultCollapsed": true,
+      "children": [],
+      "frameworks": [
+        {
+          "label": "react",
+          "children": [
+            {
+              "label": "createFormHook()",
+              "to": "framework/react/reference/functions/createFormHook"
+            },
+            {
+              "label": "CreateFormHookOptions",
+              "to": "framework/react/reference/interfaces/CreateFormHookOptions"
+            },
+            {
+              "label": "AppFormHookResult",
+              "to": "framework/react/reference/interfaces/AppFormHookResult"
+            },
+            {
+              "label": "FormHookHelpers",
+              "to": "framework/react/reference/interfaces/FormHookHelpers"
+            },
+            {
+              "label": "FieldBrandHelper",
+              "to": "framework/react/reference/interfaces/FieldBrandHelper"
+            },
+            {
+              "label": "FieldComponentHelper",
+              "to": "framework/react/reference/interfaces/FieldComponentHelper"
+            },
+            {
+              "label": "defineFieldGroup()",
+              "to": "framework/react/reference/variables/defineFieldGroup"
+            },
+            {
+              "label": "FieldGroupApi",
+              "to": "framework/react/reference/interfaces/FieldGroupApi"
+            },
+            {
+              "label": "FieldGroupDefinition",
+              "to": "framework/react/reference/interfaces/FieldGroupDefinition"
+            },
+            {
+              "label": "FieldGroupHelper",
+              "to": "framework/react/reference/interfaces/FieldGroupHelper"
+            }
+          ]
+        }
+      ]
+    },
     {
       "label": "FormApi Reference",
       "collapsible": true,

docs/framework/preact/reference/interfaces/AppFormHookResult.md

@@ -5,14 +5,19 @@ title: AppFormHookResult
 
 # Interface: AppFormHookResult\<TComponents\>
 
-Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:25](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L25)
+Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:31](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L31)
+
+App Form hooks and helpers bound to the components registered with
+`createFormHook`.
 
 ## Type Parameters
 
 ### TComponents
 
 `TComponents` *extends* [`AnyPreactFormComponentMap`](../type-aliases/AnyPreactFormComponentMap.md)
 
+Library-managed. Do not specify explicitly.
+
 ## Properties
 
 ### appFormOptions
@@ -21,7 +26,31 @@ Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:25](
 appFormOptions: AppFormOptionsApi<TComponents>;
 ```
 
-Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:28](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L28)
+Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:58](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L58)
+
+Defines reusable form options that retain the components registered with
+`createFormHook`.
+
+Use the result with `PreactFormType` when a child component needs the type
+of one known App Form, including its registered field and form components.
+
+#### Example
+
+```tsx
+const profileOptions = appFormOptions({
+  defaultValues: { name: '' },
+})
+
+type ProfileForm = PreactFormType<typeof profileOptions>
+
+function NameField({ form }: { form: ProfileForm }) {
+  return (
+    <form.Field name="name">
+      {(field) => <field.TextField label="Name" />}
+    </form.Field>
+  )
+}
+```
 
 ***
 
@@ -31,7 +60,31 @@ Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:28](
 defineAppFieldGroup: DefineFieldGroupFn<TComponents["fieldComponents"]>;
 ```
 
-Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:29](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L29)
+Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:83](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L83)
+
+Defines a reusable field group whose fields expose the field components
+registered with `createFormHook`.
+
+#### Example
+
+```tsx
+const contactFields = defineAppFieldGroup(({ strict }) => ({
+  name: strict<string>(),
+  email: strict<string>(),
+}))
+
+function ContactFields({
+  fields,
+}: {
+  fields: typeof contactFields.fields
+}) {
+  return (
+    <fields.Field name="name">
+      {(field) => <field.TextField label="Name" />}
+    </fields.Field>
+  )
+}
+```
 
 ***
 
@@ -41,7 +94,31 @@ Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:29](
 useAppForm: UseAppFormHook<TComponents>;
 ```
 
-Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:30](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L30)
+Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:108](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L108)
+
+Creates a Preact form API extended with the field and form components
+registered with `createFormHook`.
+
+Form data, validators, and submission results are inferred from the passed
+options.
+
+#### Example
+
+```tsx
+function ProfileForm() {
+  const form = useAppForm({
+    defaultValues: { name: '' },
+  })
+
+  return (
+    <form.AppForm>
+      <form.Field name="name">
+        {(field) => <field.TextField label="Name" />}
+      </form.Field>
+    </form.AppForm>
+  )
+}
+```
 
 ***
 
@@ -51,8 +128,31 @@ Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:30](
 useFormContext: () => PreactAppFormApi<any, any, TComponents>;
 ```
 
-Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:31](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L31)
+Defined in: [packages/preact-form/src/AppForm/createFormHookTypes.public.ts:132](https://github.com/TanStack/form/blob/main/packages/preact-form/src/AppForm/createFormHookTypes.public.ts#L132)
+
+Reads the current App Form API from the nearest `form.AppForm` provider.
+
+Use this hook inside form components registered with `createFormHook`. It
+throws when called outside a `form.AppForm` subtree.
 
 #### Returns
 
 [`PreactAppFormApi`](../type-aliases/PreactAppFormApi.md)\<`any`, `any`, `TComponents`\>
+
+#### Example
+
+```tsx
+function SubmitButton({ label }: { label: string }) {
+  const form = useFormContext()
+
+  return (
+    <form.Subscribe selector={(state) => state.isSubmitting}>
+      {(isSubmitting) => (
+        <button type="submit" disabled={isSubmitting}>
+          {label}
+        </button>
+      )}
+    </form.Subscribe>
+  )
+}
+```

docs/framework/react/reference/functions/createFormHook.md

@@ -6,23 +6,33 @@ title: createFormHook
 # Function: createFormHook()
 
 ```ts
-function createFormHook<TComponents>(createOptions): AppFormHookResult<TComponents>;
+function createFormHook<TFormComponents, TFieldComponents>(createOptions): AppFormHookResult<{
+  fieldComponents: TFieldComponents;
+  formComponents: TFormComponents;
+}>;
 ```
 
-Defined in: [packages/react-form/src/AppForm/createFormHook.public.ts:20](https://github.com/TanStack/form/blob/main/packages/react-form/src/AppForm/createFormHook.public.ts#L20)
+Defined in: [packages/react-form/src/AppForm/createFormHook.public.ts:21](https://github.com/TanStack/form/blob/main/packages/react-form/src/AppForm/createFormHook.public.ts#L21)
 
 ## Type Parameters
 
-### TComponents
+### TFormComponents
 
-`TComponents` *extends* [`AnyReactFormComponentMap`](../type-aliases/AnyReactFormComponentMap.md)
+`TFormComponents` *extends* `Record`\<`string`, `FunctionComponent`\<`any`\>\>
+
+### TFieldComponents
+
+`TFieldComponents` *extends* `Record`\<`string`, `FunctionComponent`\<`any`\>\>
 
 ## Parameters
 
 ### createOptions
 
-`TComponents`
+[`CreateFormHookOptions`](../interfaces/CreateFormHookOptions.md)\<`TFormComponents`, `TFieldComponents`\>
 
 ## Returns
 
-[`AppFormHookResult`](../interfaces/AppFormHookResult.md)\<`TComponents`\>
+[`AppFormHookResult`](../interfaces/AppFormHookResult.md)\<\{
+  `fieldComponents`: `TFieldComponents`;
+  `formComponents`: `TFormComponents`;
+\}\>

docs/framework/react/reference/functions/getFormHookHelpers.md

@@ -9,8 +9,39 @@ title: getFormHookHelpers
 function getFormHookHelpers(): FormHookHelpers;
 ```
 
-Defined in: [packages/react-form/src/AppForm/getFormHookHelpers.public.ts:101](https://github.com/TanStack/form/blob/main/packages/react-form/src/AppForm/getFormHookHelpers.public.ts#L101)
+Defined in: [packages/react-form/src/AppForm/getFormHookHelpers.public.ts:268](https://github.com/TanStack/form/blob/main/packages/react-form/src/AppForm/getFormHookHelpers.public.ts#L268)
+
+Creates helpers that make React field components value-aware for
+`createFormHook`.
+
+`fieldComponent` injects the current App Form field API into a selected prop.
+`fieldBrand` only adds compile-time field-value compatibility and returns the
+original component at runtime.
 
 ## Returns
 
 [`FormHookHelpers`](../interfaces/FormHookHelpers.md)
+
+## Example
+
+```tsx
+import { createFormHook, getFormHookHelpers } from '@tanstack/react-form'
+import type { FieldWithValue } from '@tanstack/react-form'
+
+function TextInput({ field }: { field: FieldWithValue<string> }) {
+  return (
+    <input
+      value={field.value}
+      onChange={(event) => field.handleChange(event.target.value)}
+    />
+  )
+}
+
+const { fieldComponent } = getFormHookHelpers()
+const TextField = fieldComponent.strict(TextInput, 'field')
+
+export const { useAppForm } = createFormHook({
+  fieldComponents: { TextField },
+  formComponents: {},
+})
+```

docs/framework/react/reference/index.md

@@ -18,6 +18,9 @@ title: "@tanstack/react-form"
 - [Atom](interfaces/Atom.md)
 - [AtomOptions](interfaces/AtomOptions.md)
 - [BaseAtom](interfaces/BaseAtom.md)
+- [CreateFormHookOptions](interfaces/CreateFormHookOptions.md)
+- [FieldBrandHelper](interfaces/FieldBrandHelper.md)
+- [FieldComponentHelper](interfaces/FieldComponentHelper.md)
 - [FieldGroupApi](interfaces/FieldGroupApi.md)
 - [FieldGroupArrayFieldComponent](interfaces/FieldGroupArrayFieldComponent.md)
 - [FieldGroupDefinition](interfaces/FieldGroupDefinition.md)
@@ -50,6 +53,9 @@ title: "@tanstack/react-form"
 - [AnyReactFormApi](type-aliases/AnyReactFormApi.md)
 - [AnyReactFormComponentMap](type-aliases/AnyReactFormComponentMap.md)
 - [AppFormComponent](type-aliases/AppFormComponent.md)
+- [CreateFormHookDefaultFieldOptions](type-aliases/CreateFormHookDefaultFieldOptions.md)
+- [CreateFormHookDefaultFormGroupOptions](type-aliases/CreateFormHookDefaultFormGroupOptions.md)
+- [CreateFormHookDefaultFormOptions](type-aliases/CreateFormHookDefaultFormOptions.md)
 - [DefaultReactFormComponentMap](type-aliases/DefaultReactFormComponentMap.md)
 - [DefineFieldGroupFn](type-aliases/DefineFieldGroupFn.md)
 - [FieldGroupFieldBindingForSlot](type-aliases/FieldGroupFieldBindingForSlot.md)