@tanstack/react-form 0.23.2 → 0.24.0

package/dist/cjs/types.d.cts

@@ -1,6 +1,9 @@
 import { DeepKeys, DeepValue, FieldApiOptions, Validator } from '@tanstack/form-core';
 import { FunctionComponent } from 'react';
 
+/**
+ * The field options.
+ */
 export type UseFieldOptions<TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>> = FieldApiOptions<TParentData, TName, TFieldValidator, TFormValidator, TData> & {
     mode?: 'value' | 'array';
 };

package/dist/cjs/useField.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useField.cjs","sources":["../../src/useField.tsx"],"sourcesContent":["import React, { type FunctionComponent, useState } from 'react'\nimport { useStore } from '@tanstack/react-store'\nimport { FieldApi, functionalUpdate } from '@tanstack/form-core'\nimport { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'\nimport type { NodeType, UseFieldOptions } from './types'\nimport type { DeepKeys, DeepValue, Validator } from '@tanstack/form-core'\n\ndeclare module '@tanstack/form-core' {\n  // eslint-disable-next-line no-shadow\n  interface FieldApi<\n    TParentData,\n    TName extends DeepKeys<TParentData>,\n    TFieldValidator extends\n      | Validator<DeepValue<TParentData, TName>, unknown>\n      | undefined = undefined,\n    TFormValidator extends\n      | Validator<TParentData, unknown>\n      | undefined = undefined,\n    TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n  > {\n    Field: FieldComponent<TParentData, TFormValidator>\n  }\n}\n\nexport type UseField<\n  TParentData,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n> = <\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>(\n  opts: Omit<\n    UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>,\n    'form'\n  >,\n) => FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>\n\nexport function useField<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>(\n  opts: UseFieldOptions<\n    TParentData,\n    TName,\n    TFieldValidator,\n    TFormValidator,\n    TData\n  >,\n): FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData> {\n  const [fieldApi] = useState(() => {\n    const api = new FieldApi({\n      ...opts,\n      form: opts.form,\n      name: opts.name,\n    })\n\n    api.Field = Field as never\n\n    return api\n  })\n\n  useIsomorphicLayoutEffect(fieldApi.mount, [fieldApi])\n\n  /**\n   * fieldApi.update should not have any side effects. Think of it like a `useRef`\n   * that we need to keep updated every render with the most up-to-date information.\n   */\n  useIsomorphicLayoutEffect(() => {\n    fieldApi.update(opts)\n  })\n\n  useStore(\n    fieldApi.store,\n    opts.mode === 'array'\n      ? (state) => {\n          return [state.meta, Object.keys(state.value as never).length]\n        }\n      : undefined,\n  )\n\n  return fieldApi as never\n}\n\ntype FieldComponentProps<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n> = {\n  children: (\n    fieldApi: FieldApi<\n      TParentData,\n      TName,\n      TFieldValidator,\n      TFormValidator,\n      TData\n    >,\n  ) => NodeType\n} & UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>\n\nexport type FieldComponent<\n  TParentData,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n> = <\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>({\n  children,\n  ...fieldOptions\n}: Omit<\n  FieldComponentProps<\n    TParentData,\n    TName,\n    TFieldValidator,\n    TFormValidator,\n    TData\n  >,\n  'form'\n>) => NodeType\n\nexport const Field = (<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>({\n  children,\n  ...fieldOptions\n}: FieldComponentProps<\n  TParentData,\n  TName,\n  TFieldValidator,\n  TFormValidator,\n  TData\n>): NodeType => {\n  const fieldApi = useField(fieldOptions as any)\n\n  return (<>{functionalUpdate(children, fieldApi as any)}</>) as never\n}) satisfies FunctionComponent<FieldComponentProps<any, any, any, any, any>>\n"],"names":["useState","FieldApi","useIsomorphicLayoutEffect","useStore","jsx","Fragment","functionalUpdate"],"mappings":";;;;;;;AA0CO,SAAS,SAWd,MAOsE;AACtE,QAAM,CAAC,QAAQ,IAAIA,MAAAA,SAAS,MAAM;AAC1B,UAAA,MAAM,IAAIC,kBAAS;AAAA,MACvB,GAAG;AAAA,MACH,MAAM,KAAK;AAAA,MACX,MAAM,KAAK;AAAA,IAAA,CACZ;AAED,QAAI,QAAQ;AAEL,WAAA;AAAA,EAAA,CACR;AAEDC,4BAAAA,0BAA0B,SAAS,OAAO,CAAC,QAAQ,CAAC;AAMpDA,4BAAAA,0BAA0B,MAAM;AAC9B,aAAS,OAAO,IAAI;AAAA,EAAA,CACrB;AAEDC,aAAA;AAAA,IACE,SAAS;AAAA,IACT,KAAK,SAAS,UACV,CAAC,UAAU;AACF,aAAA,CAAC,MAAM,MAAM,OAAO,KAAK,MAAM,KAAc,EAAE,MAAM;AAAA,IAE9D,IAAA;AAAA,EAAA;AAGC,SAAA;AACT;AAiDO,MAAM,QAAS,CAUpB;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAMgB;AACR,QAAA,WAAW,SAAS,YAAmB;AAE7C,SAAWC,2BAAA,IAAAC,WAAA,UAAA,EAAA,UAAAC,SAAA,iBAAiB,UAAU,QAAe,EAAE,CAAA;AACzD;;;"}
+{"version":3,"file":"useField.cjs","sources":["../../src/useField.tsx"],"sourcesContent":["import React, { type FunctionComponent, useState } from 'react'\nimport { useStore } from '@tanstack/react-store'\nimport { FieldApi, functionalUpdate } from '@tanstack/form-core'\nimport { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'\nimport type { NodeType, UseFieldOptions } from './types'\nimport type { DeepKeys, DeepValue, Validator } from '@tanstack/form-core'\n\ndeclare module '@tanstack/form-core' {\n  /**\n   * When using `@tanstack/react-form`, the core field API is extended at type level with additional methods for React-specific functionality:\n   */\n  // eslint-disable-next-line no-shadow\n  interface FieldApi<\n    TParentData,\n    TName extends DeepKeys<TParentData>,\n    TFieldValidator extends\n      | Validator<DeepValue<TParentData, TName>, unknown>\n      | undefined = undefined,\n    TFormValidator extends\n      | Validator<TParentData, unknown>\n      | undefined = undefined,\n    TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n  > {\n    /**\n     * A pre-bound and type-safe sub-field component using this field as a root.\n     */\n    Field: FieldComponent<TParentData, TFormValidator>\n  }\n}\n\n/**\n * A type representing a hook for using a field in a form with the given form data type.\n *\n * A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field.\n */\nexport type UseField<\n  TParentData,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n> = <\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>(\n  opts: Omit<\n    UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>,\n    'form'\n  >,\n) => FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>\n\n/**\n * A hook for managing a field in a form.\n * @param opts An object with field options.\n *\n * @returns The `FieldApi` instance for the specified field.\n */\nexport function useField<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>(\n  opts: UseFieldOptions<\n    TParentData,\n    TName,\n    TFieldValidator,\n    TFormValidator,\n    TData\n  >,\n): FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData> {\n  const [fieldApi] = useState(() => {\n    const api = new FieldApi({\n      ...opts,\n      form: opts.form,\n      name: opts.name,\n    })\n\n    api.Field = Field as never\n\n    return api\n  })\n\n  useIsomorphicLayoutEffect(fieldApi.mount, [fieldApi])\n\n  /**\n   * fieldApi.update should not have any side effects. Think of it like a `useRef`\n   * that we need to keep updated every render with the most up-to-date information.\n   */\n  useIsomorphicLayoutEffect(() => {\n    fieldApi.update(opts)\n  })\n\n  useStore(\n    fieldApi.store,\n    opts.mode === 'array'\n      ? (state) => {\n          return [state.meta, Object.keys(state.value as never).length]\n        }\n      : undefined,\n  )\n\n  return fieldApi as never\n}\n\n/**\n * @param children A render function that takes a field API instance and returns a React element.\n */\ntype FieldComponentProps<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n> = {\n  children: (\n    fieldApi: FieldApi<\n      TParentData,\n      TName,\n      TFieldValidator,\n      TFormValidator,\n      TData\n    >,\n  ) => NodeType\n} & UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>\n\n/**\n * A type alias representing a field component for a specific form data type.\n */\nexport type FieldComponent<\n  TParentData,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n> = <\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>({\n  children,\n  ...fieldOptions\n}: Omit<\n  FieldComponentProps<\n    TParentData,\n    TName,\n    TFieldValidator,\n    TFormValidator,\n    TData\n  >,\n  'form'\n>) => NodeType\n\n/**\n * A function component that takes field options and a render function as children and returns a React component.\n *\n * The `Field` component uses the `useField` hook internally to manage the field instance.\n */\nexport const Field = (<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>({\n  children,\n  ...fieldOptions\n}: FieldComponentProps<\n  TParentData,\n  TName,\n  TFieldValidator,\n  TFormValidator,\n  TData\n>): NodeType => {\n  const fieldApi = useField(fieldOptions as any)\n\n  return (<>{functionalUpdate(children, fieldApi as any)}</>) as never\n}) satisfies FunctionComponent<FieldComponentProps<any, any, any, any, any>>\n"],"names":["useState","FieldApi","useIsomorphicLayoutEffect","useStore","jsx","Fragment","functionalUpdate"],"mappings":";;;;;;;AA2DO,SAAS,SAWd,MAOsE;AACtE,QAAM,CAAC,QAAQ,IAAIA,MAAAA,SAAS,MAAM;AAC1B,UAAA,MAAM,IAAIC,kBAAS;AAAA,MACvB,GAAG;AAAA,MACH,MAAM,KAAK;AAAA,MACX,MAAM,KAAK;AAAA,IAAA,CACZ;AAED,QAAI,QAAQ;AAEL,WAAA;AAAA,EAAA,CACR;AAEDC,4BAAAA,0BAA0B,SAAS,OAAO,CAAC,QAAQ,CAAC;AAMpDA,4BAAAA,0BAA0B,MAAM;AAC9B,aAAS,OAAO,IAAI;AAAA,EAAA,CACrB;AAEDC,aAAA;AAAA,IACE,SAAS;AAAA,IACT,KAAK,SAAS,UACV,CAAC,UAAU;AACF,aAAA,CAAC,MAAM,MAAM,OAAO,KAAK,MAAM,KAAc,EAAE,MAAM;AAAA,IAE9D,IAAA;AAAA,EAAA;AAGC,SAAA;AACT;AA4DO,MAAM,QAAS,CAUpB;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAMgB;AACR,QAAA,WAAW,SAAS,YAAmB;AAE7C,SAAWC,2BAAA,IAAAC,WAAA,UAAA,EAAA,UAAAC,SAAA,iBAAiB,UAAU,QAAe,EAAE,CAAA;AACzD;;;"}

package/dist/cjs/useField.d.cts

@@ -2,15 +2,43 @@ import { FieldApi, DeepKeys, DeepValue, Validator } from '@tanstack/form-core';
 import { NodeType, UseFieldOptions } from './types.cjs';
 
 declare module '@tanstack/form-core' {
+    /**
+     * When using `@tanstack/react-form`, the core field API is extended at type level with additional methods for React-specific functionality:
+     */
     interface FieldApi<TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>> {
+        /**
+         * A pre-bound and type-safe sub-field component using this field as a root.
+         */
         Field: FieldComponent<TParentData, TFormValidator>;
     }
 }
+/**
+ * A type representing a hook for using a field in a form with the given form data type.
+ *
+ * A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field.
+ */
 export type UseField<TParentData, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined> = <TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>>(opts: Omit<UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>, 'form'>) => FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>;
+/**
+ * A hook for managing a field in a form.
+ * @param opts An object with field options.
+ *
+ * @returns The `FieldApi` instance for the specified field.
+ */
 export declare function useField<TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>>(opts: UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>): FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>;
+/**
+ * @param children A render function that takes a field API instance and returns a React element.
+ */
 type FieldComponentProps<TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>> = {
     children: (fieldApi: FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>) => NodeType;
 } & UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>;
+/**
+ * A type alias representing a field component for a specific form data type.
+ */
 export type FieldComponent<TParentData, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined> = <TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>>({ children, ...fieldOptions }: Omit<FieldComponentProps<TParentData, TName, TFieldValidator, TFormValidator, TData>, 'form'>) => NodeType;
+/**
+ * A function component that takes field options and a render function as children and returns a React component.
+ *
+ * The `Field` component uses the `useField` hook internally to manage the field instance.
+ */
 export declare const Field: <TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>>({ children, ...fieldOptions }: FieldComponentProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) => NodeType;
 export {};

package/dist/cjs/useForm.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useForm.cjs","sources":["../../src/useForm.tsx"],"sourcesContent":["import { FormApi, functionalUpdate } from '@tanstack/form-core'\nimport { useStore } from '@tanstack/react-store'\nimport React, { useState } from 'react'\nimport { Field, type FieldComponent, type UseField, useField } from './useField'\nimport { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'\nimport type { NoInfer } from '@tanstack/react-store'\nimport type { FormOptions, FormState, Validator } from '@tanstack/form-core'\nimport type { NodeType } from './types'\n\ndeclare module '@tanstack/form-core' {\n  // eslint-disable-next-line no-shadow\n  interface FormApi<TFormData, TFormValidator> {\n    Field: FieldComponent<TFormData, TFormValidator>\n    useField: UseField<TFormData, TFormValidator>\n    useStore: <TSelected = NoInfer<FormState<TFormData>>>(\n      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected,\n    ) => TSelected\n    Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {\n      /**\n      TypeScript versions <=5.0.4 have a bug that prevents\n      the type of the `TSelected` generic from being inferred\n      from the return type of this method.\n\n      In these versions, `TSelected` will fall back to the default\n      type (or `unknown` if that's not defined).\n\n      @see {@link https://github.com/TanStack/form/pull/606/files#r1506715714 | This discussion on GitHub for the details}\n      @see {@link https://github.com/microsoft/TypeScript/issues/52786 | The bug report in `microsoft/TypeScript`}\n      */\n      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected\n      children: ((state: NoInfer<TSelected>) => NodeType) | NodeType\n    }) => NodeType\n  }\n}\n\nexport function useForm<\n  TFormData,\n  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,\n>(\n  opts?: FormOptions<TFormData, TFormValidator>,\n): FormApi<TFormData, TFormValidator> {\n  const [formApi] = useState(() => {\n    const api = new FormApi<TFormData, TFormValidator>(opts)\n    api.Field = function APIField(props) {\n      return (<Field {...props} form={api} />) as never\n    }\n    // eslint-disable-next-line react-hooks/rules-of-hooks\n    api.useField = (props) => useField({ ...props, form: api })\n    api.useStore = (\n      // @ts-ignore\n      selector,\n    ) => {\n      // eslint-disable-next-line react-hooks/rules-of-hooks\n      return useStore(api.store as any, selector as any) as any\n    }\n    api.Subscribe = (\n      // @ts-ignore\n      props,\n    ) => {\n      return functionalUpdate(\n        props.children,\n        // eslint-disable-next-line react-hooks/rules-of-hooks\n        useStore(api.store as any, props.selector as any),\n      ) as any\n    }\n\n    return api\n  })\n\n  useIsomorphicLayoutEffect(formApi.mount, [])\n\n  formApi.useStore((state) => state.isSubmitting)\n\n  /**\n   * formApi.update should not have any side effects. Think of it like a `useRef`\n   * that we need to keep updated every render with the most up-to-date information.\n   */\n  useIsomorphicLayoutEffect(() => {\n    formApi.update(opts)\n  })\n\n  return formApi as any\n}\n"],"names":["useState","FormApi","jsx","Field","useField","useStore","functionalUpdate","useIsomorphicLayoutEffect"],"mappings":";;;;;;;;AAmCO,SAAS,QAId,MACoC;AACpC,QAAM,CAAC,OAAO,IAAIA,MAAAA,SAAS,MAAM;AACzB,UAAA,MAAM,IAAIC,iBAAmC,IAAI;AACnD,QAAA,QAAQ,SAAS,SAAS,OAAO;AACnC,aAASC,2BAAAA,IAAAC,SAAAA,OAAA,EAAO,GAAG,OAAO,MAAM,IAAK,CAAA;AAAA,IAAA;AAGnC,QAAA,WAAW,CAAC,UAAUC,SAAA,SAAS,EAAE,GAAG,OAAO,MAAM,IAAA,CAAK;AACtD,QAAA,WAAW,CAEb,aACG;AAEI,aAAAC,oBAAS,IAAI,OAAc,QAAe;AAAA,IAAA;AAE/C,QAAA,YAAY,CAEd,UACG;AACI,aAAAC,SAAA;AAAA,QACL,MAAM;AAAA;AAAA,QAEND,WAAAA,SAAS,IAAI,OAAc,MAAM,QAAe;AAAA,MAAA;AAAA,IAClD;AAGK,WAAA;AAAA,EAAA,CACR;AAEyBE,4BAAAA,0BAAA,QAAQ,OAAO,CAAA,CAAE;AAE3C,UAAQ,SAAS,CAAC,UAAU,MAAM,YAAY;AAM9CA,4BAAAA,0BAA0B,MAAM;AAC9B,YAAQ,OAAO,IAAI;AAAA,EAAA,CACpB;AAEM,SAAA;AACT;;"}
+{"version":3,"file":"useForm.cjs","sources":["../../src/useForm.tsx"],"sourcesContent":["import { FormApi, functionalUpdate } from '@tanstack/form-core'\nimport { useStore } from '@tanstack/react-store'\nimport React, { useState } from 'react'\nimport { Field, type FieldComponent, type UseField, useField } from './useField'\nimport { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'\nimport type { NoInfer } from '@tanstack/react-store'\nimport type { FormOptions, FormState, Validator } from '@tanstack/form-core'\nimport type { NodeType } from './types'\n\ndeclare module '@tanstack/form-core' {\n  /**\n   * When using `@tanstack/react-form`, the core form API is extended at type level with additional methods for React-specific functionality:\n   */\n  // eslint-disable-next-line no-shadow\n  interface FormApi<TFormData, TFormValidator> {\n    /**\n     * A React component to render form fields. With this, you can render and manage individual form fields.\n     */\n    Field: FieldComponent<TFormData, TFormValidator>\n    /**\n     * A custom React hook that provides functionalities related to individual form fields. It gives you access to field values, errors, and allows you to set or update field values.\n     */\n    useField: UseField<TFormData, TFormValidator>\n    /**\n     * A `useStore` hook that connects to the internal store of the form. It can be used to access the form's current state or any other related state information. You can optionally pass in a selector function to cherry-pick specific parts of the state\n     */\n    useStore: <TSelected = NoInfer<FormState<TFormData>>>(\n      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected,\n    ) => TSelected\n    /**\n     * A `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates.\n     */\n    Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {\n      /**\n      TypeScript versions <=5.0.4 have a bug that prevents\n      the type of the `TSelected` generic from being inferred\n      from the return type of this method.\n\n      In these versions, `TSelected` will fall back to the default\n      type (or `unknown` if that's not defined).\n\n      @see {@link https://github.com/TanStack/form/pull/606/files#r1506715714 | This discussion on GitHub for the details}\n      @see {@link https://github.com/microsoft/TypeScript/issues/52786 | The bug report in `microsoft/TypeScript`}\n      */\n      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected\n      children: ((state: NoInfer<TSelected>) => NodeType) | NodeType\n    }) => NodeType\n  }\n}\n\n/**\n * A custom React Hook that returns an instance of the `FormApi` class.\n *\n * This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields\n */\nexport function useForm<\n  TFormData,\n  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,\n>(\n  opts?: FormOptions<TFormData, TFormValidator>,\n): FormApi<TFormData, TFormValidator> {\n  const [formApi] = useState(() => {\n    const api = new FormApi<TFormData, TFormValidator>(opts)\n    api.Field = function APIField(props) {\n      return (<Field {...props} form={api} />) as never\n    }\n    // eslint-disable-next-line react-hooks/rules-of-hooks\n    api.useField = (props) => useField({ ...props, form: api })\n    api.useStore = (\n      // @ts-ignore\n      selector,\n    ) => {\n      // eslint-disable-next-line react-hooks/rules-of-hooks\n      return useStore(api.store as any, selector as any) as any\n    }\n    api.Subscribe = (\n      // @ts-ignore\n      props,\n    ) => {\n      return functionalUpdate(\n        props.children,\n        // eslint-disable-next-line react-hooks/rules-of-hooks\n        useStore(api.store as any, props.selector as any),\n      ) as any\n    }\n\n    return api\n  })\n\n  useIsomorphicLayoutEffect(formApi.mount, [])\n\n  formApi.useStore((state) => state.isSubmitting)\n\n  /**\n   * formApi.update should not have any side effects. Think of it like a `useRef`\n   * that we need to keep updated every render with the most up-to-date information.\n   */\n  useIsomorphicLayoutEffect(() => {\n    formApi.update(opts)\n  })\n\n  return formApi as any\n}\n"],"names":["useState","FormApi","jsx","Field","useField","useStore","functionalUpdate","useIsomorphicLayoutEffect"],"mappings":";;;;;;;;AAuDO,SAAS,QAId,MACoC;AACpC,QAAM,CAAC,OAAO,IAAIA,MAAAA,SAAS,MAAM;AACzB,UAAA,MAAM,IAAIC,iBAAmC,IAAI;AACnD,QAAA,QAAQ,SAAS,SAAS,OAAO;AACnC,aAASC,2BAAAA,IAAAC,SAAAA,OAAA,EAAO,GAAG,OAAO,MAAM,IAAK,CAAA;AAAA,IAAA;AAGnC,QAAA,WAAW,CAAC,UAAUC,SAAA,SAAS,EAAE,GAAG,OAAO,MAAM,IAAA,CAAK;AACtD,QAAA,WAAW,CAEb,aACG;AAEI,aAAAC,oBAAS,IAAI,OAAc,QAAe;AAAA,IAAA;AAE/C,QAAA,YAAY,CAEd,UACG;AACI,aAAAC,SAAA;AAAA,QACL,MAAM;AAAA;AAAA,QAEND,WAAAA,SAAS,IAAI,OAAc,MAAM,QAAe;AAAA,MAAA;AAAA,IAClD;AAGK,WAAA;AAAA,EAAA,CACR;AAEyBE,4BAAAA,0BAAA,QAAQ,OAAO,CAAA,CAAE;AAE3C,UAAQ,SAAS,CAAC,UAAU,MAAM,YAAY;AAM9CA,4BAAAA,0BAA0B,MAAM;AAC9B,YAAQ,OAAO,IAAI;AAAA,EAAA,CACpB;AAEM,SAAA;AACT;;"}

package/dist/cjs/useForm.d.cts

@@ -4,10 +4,25 @@ import { NoInfer } from '@tanstack/react-store';
 import { NodeType } from './types.cjs';
 
 declare module '@tanstack/form-core' {
+    /**
+     * When using `@tanstack/react-form`, the core form API is extended at type level with additional methods for React-specific functionality:
+     */
     interface FormApi<TFormData, TFormValidator> {
+        /**
+         * A React component to render form fields. With this, you can render and manage individual form fields.
+         */
         Field: FieldComponent<TFormData, TFormValidator>;
+        /**
+         * A custom React hook that provides functionalities related to individual form fields. It gives you access to field values, errors, and allows you to set or update field values.
+         */
         useField: UseField<TFormData, TFormValidator>;
+        /**
+         * A `useStore` hook that connects to the internal store of the form. It can be used to access the form's current state or any other related state information. You can optionally pass in a selector function to cherry-pick specific parts of the state
+         */
         useStore: <TSelected = NoInfer<FormState<TFormData>>>(selector?: (state: NoInfer<FormState<TFormData>>) => TSelected) => TSelected;
+        /**
+         * A `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates.
+         */
         Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {
             /**
             TypeScript versions <=5.0.4 have a bug that prevents
@@ -25,4 +40,9 @@ declare module '@tanstack/form-core' {
         }) => NodeType;
     }
 }
+/**
+ * A custom React Hook that returns an instance of the `FormApi` class.
+ *
+ * This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields
+ */
 export declare function useForm<TFormData, TFormValidator extends Validator<TFormData, unknown> | undefined = undefined>(opts?: FormOptions<TFormData, TFormValidator>): FormApi<TFormData, TFormValidator>;

package/dist/esm/types.d.ts

@@ -1,6 +1,9 @@
 import { DeepKeys, DeepValue, FieldApiOptions, Validator } from '@tanstack/form-core';
 import { FunctionComponent } from 'react';
 
+/**
+ * The field options.
+ */
 export type UseFieldOptions<TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>> = FieldApiOptions<TParentData, TName, TFieldValidator, TFormValidator, TData> & {
     mode?: 'value' | 'array';
 };

package/dist/esm/useField.d.ts

@@ -2,15 +2,43 @@ import { FieldApi, DeepKeys, DeepValue, Validator } from '@tanstack/form-core';
 import { NodeType, UseFieldOptions } from './types.js';
 
 declare module '@tanstack/form-core' {
+    /**
+     * When using `@tanstack/react-form`, the core field API is extended at type level with additional methods for React-specific functionality:
+     */
     interface FieldApi<TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>> {
+        /**
+         * A pre-bound and type-safe sub-field component using this field as a root.
+         */
         Field: FieldComponent<TParentData, TFormValidator>;
     }
 }
+/**
+ * A type representing a hook for using a field in a form with the given form data type.
+ *
+ * A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field.
+ */
 export type UseField<TParentData, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined> = <TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>>(opts: Omit<UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>, 'form'>) => FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>;
+/**
+ * A hook for managing a field in a form.
+ * @param opts An object with field options.
+ *
+ * @returns The `FieldApi` instance for the specified field.
+ */
 export declare function useField<TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>>(opts: UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>): FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>;
+/**
+ * @param children A render function that takes a field API instance and returns a React element.
+ */
 type FieldComponentProps<TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>> = {
     children: (fieldApi: FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>) => NodeType;
 } & UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>;
+/**
+ * A type alias representing a field component for a specific form data type.
+ */
 export type FieldComponent<TParentData, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined> = <TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>>({ children, ...fieldOptions }: Omit<FieldComponentProps<TParentData, TName, TFieldValidator, TFormValidator, TData>, 'form'>) => NodeType;
+/**
+ * A function component that takes field options and a render function as children and returns a React component.
+ *
+ * The `Field` component uses the `useField` hook internally to manage the field instance.
+ */
 export declare const Field: <TParentData, TName extends DeepKeys<TParentData>, TFieldValidator extends Validator<DeepValue<TParentData, TName>, unknown> | undefined = undefined, TFormValidator extends Validator<TParentData, unknown> | undefined = undefined, TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>>({ children, ...fieldOptions }: FieldComponentProps<TParentData, TName, TFieldValidator, TFormValidator, TData>) => NodeType;
 export {};

package/dist/esm/useField.js.map

@@ -1 +1 @@
-{"version":3,"file":"useField.js","sources":["../../src/useField.tsx"],"sourcesContent":["import React, { type FunctionComponent, useState } from 'react'\nimport { useStore } from '@tanstack/react-store'\nimport { FieldApi, functionalUpdate } from '@tanstack/form-core'\nimport { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'\nimport type { NodeType, UseFieldOptions } from './types'\nimport type { DeepKeys, DeepValue, Validator } from '@tanstack/form-core'\n\ndeclare module '@tanstack/form-core' {\n  // eslint-disable-next-line no-shadow\n  interface FieldApi<\n    TParentData,\n    TName extends DeepKeys<TParentData>,\n    TFieldValidator extends\n      | Validator<DeepValue<TParentData, TName>, unknown>\n      | undefined = undefined,\n    TFormValidator extends\n      | Validator<TParentData, unknown>\n      | undefined = undefined,\n    TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n  > {\n    Field: FieldComponent<TParentData, TFormValidator>\n  }\n}\n\nexport type UseField<\n  TParentData,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n> = <\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>(\n  opts: Omit<\n    UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>,\n    'form'\n  >,\n) => FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>\n\nexport function useField<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>(\n  opts: UseFieldOptions<\n    TParentData,\n    TName,\n    TFieldValidator,\n    TFormValidator,\n    TData\n  >,\n): FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData> {\n  const [fieldApi] = useState(() => {\n    const api = new FieldApi({\n      ...opts,\n      form: opts.form,\n      name: opts.name,\n    })\n\n    api.Field = Field as never\n\n    return api\n  })\n\n  useIsomorphicLayoutEffect(fieldApi.mount, [fieldApi])\n\n  /**\n   * fieldApi.update should not have any side effects. Think of it like a `useRef`\n   * that we need to keep updated every render with the most up-to-date information.\n   */\n  useIsomorphicLayoutEffect(() => {\n    fieldApi.update(opts)\n  })\n\n  useStore(\n    fieldApi.store,\n    opts.mode === 'array'\n      ? (state) => {\n          return [state.meta, Object.keys(state.value as never).length]\n        }\n      : undefined,\n  )\n\n  return fieldApi as never\n}\n\ntype FieldComponentProps<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n> = {\n  children: (\n    fieldApi: FieldApi<\n      TParentData,\n      TName,\n      TFieldValidator,\n      TFormValidator,\n      TData\n    >,\n  ) => NodeType\n} & UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>\n\nexport type FieldComponent<\n  TParentData,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n> = <\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>({\n  children,\n  ...fieldOptions\n}: Omit<\n  FieldComponentProps<\n    TParentData,\n    TName,\n    TFieldValidator,\n    TFormValidator,\n    TData\n  >,\n  'form'\n>) => NodeType\n\nexport const Field = (<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>({\n  children,\n  ...fieldOptions\n}: FieldComponentProps<\n  TParentData,\n  TName,\n  TFieldValidator,\n  TFormValidator,\n  TData\n>): NodeType => {\n  const fieldApi = useField(fieldOptions as any)\n\n  return (<>{functionalUpdate(children, fieldApi as any)}</>) as never\n}) satisfies FunctionComponent<FieldComponentProps<any, any, any, any, any>>\n"],"names":[],"mappings":";;;;;AA0CO,SAAS,SAWd,MAOsE;AACtE,QAAM,CAAC,QAAQ,IAAI,SAAS,MAAM;AAC1B,UAAA,MAAM,IAAI,SAAS;AAAA,MACvB,GAAG;AAAA,MACH,MAAM,KAAK;AAAA,MACX,MAAM,KAAK;AAAA,IAAA,CACZ;AAED,QAAI,QAAQ;AAEL,WAAA;AAAA,EAAA,CACR;AAED,4BAA0B,SAAS,OAAO,CAAC,QAAQ,CAAC;AAMpD,4BAA0B,MAAM;AAC9B,aAAS,OAAO,IAAI;AAAA,EAAA,CACrB;AAED;AAAA,IACE,SAAS;AAAA,IACT,KAAK,SAAS,UACV,CAAC,UAAU;AACF,aAAA,CAAC,MAAM,MAAM,OAAO,KAAK,MAAM,KAAc,EAAE,MAAM;AAAA,IAE9D,IAAA;AAAA,EAAA;AAGC,SAAA;AACT;AAiDO,MAAM,QAAS,CAUpB;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAMgB;AACR,QAAA,WAAW,SAAS,YAAmB;AAE7C,SAAW,oBAAA,UAAA,EAAA,UAAA,iBAAiB,UAAU,QAAe,EAAE,CAAA;AACzD;"}
+{"version":3,"file":"useField.js","sources":["../../src/useField.tsx"],"sourcesContent":["import React, { type FunctionComponent, useState } from 'react'\nimport { useStore } from '@tanstack/react-store'\nimport { FieldApi, functionalUpdate } from '@tanstack/form-core'\nimport { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'\nimport type { NodeType, UseFieldOptions } from './types'\nimport type { DeepKeys, DeepValue, Validator } from '@tanstack/form-core'\n\ndeclare module '@tanstack/form-core' {\n  /**\n   * When using `@tanstack/react-form`, the core field API is extended at type level with additional methods for React-specific functionality:\n   */\n  // eslint-disable-next-line no-shadow\n  interface FieldApi<\n    TParentData,\n    TName extends DeepKeys<TParentData>,\n    TFieldValidator extends\n      | Validator<DeepValue<TParentData, TName>, unknown>\n      | undefined = undefined,\n    TFormValidator extends\n      | Validator<TParentData, unknown>\n      | undefined = undefined,\n    TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n  > {\n    /**\n     * A pre-bound and type-safe sub-field component using this field as a root.\n     */\n    Field: FieldComponent<TParentData, TFormValidator>\n  }\n}\n\n/**\n * A type representing a hook for using a field in a form with the given form data type.\n *\n * A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field.\n */\nexport type UseField<\n  TParentData,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n> = <\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>(\n  opts: Omit<\n    UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>,\n    'form'\n  >,\n) => FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>\n\n/**\n * A hook for managing a field in a form.\n * @param opts An object with field options.\n *\n * @returns The `FieldApi` instance for the specified field.\n */\nexport function useField<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>(\n  opts: UseFieldOptions<\n    TParentData,\n    TName,\n    TFieldValidator,\n    TFormValidator,\n    TData\n  >,\n): FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData> {\n  const [fieldApi] = useState(() => {\n    const api = new FieldApi({\n      ...opts,\n      form: opts.form,\n      name: opts.name,\n    })\n\n    api.Field = Field as never\n\n    return api\n  })\n\n  useIsomorphicLayoutEffect(fieldApi.mount, [fieldApi])\n\n  /**\n   * fieldApi.update should not have any side effects. Think of it like a `useRef`\n   * that we need to keep updated every render with the most up-to-date information.\n   */\n  useIsomorphicLayoutEffect(() => {\n    fieldApi.update(opts)\n  })\n\n  useStore(\n    fieldApi.store,\n    opts.mode === 'array'\n      ? (state) => {\n          return [state.meta, Object.keys(state.value as never).length]\n        }\n      : undefined,\n  )\n\n  return fieldApi as never\n}\n\n/**\n * @param children A render function that takes a field API instance and returns a React element.\n */\ntype FieldComponentProps<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n> = {\n  children: (\n    fieldApi: FieldApi<\n      TParentData,\n      TName,\n      TFieldValidator,\n      TFormValidator,\n      TData\n    >,\n  ) => NodeType\n} & UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>\n\n/**\n * A type alias representing a field component for a specific form data type.\n */\nexport type FieldComponent<\n  TParentData,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n> = <\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>({\n  children,\n  ...fieldOptions\n}: Omit<\n  FieldComponentProps<\n    TParentData,\n    TName,\n    TFieldValidator,\n    TFormValidator,\n    TData\n  >,\n  'form'\n>) => NodeType\n\n/**\n * A function component that takes field options and a render function as children and returns a React component.\n *\n * The `Field` component uses the `useField` hook internally to manage the field instance.\n */\nexport const Field = (<\n  TParentData,\n  TName extends DeepKeys<TParentData>,\n  TFieldValidator extends\n    | Validator<DeepValue<TParentData, TName>, unknown>\n    | undefined = undefined,\n  TFormValidator extends\n    | Validator<TParentData, unknown>\n    | undefined = undefined,\n  TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,\n>({\n  children,\n  ...fieldOptions\n}: FieldComponentProps<\n  TParentData,\n  TName,\n  TFieldValidator,\n  TFormValidator,\n  TData\n>): NodeType => {\n  const fieldApi = useField(fieldOptions as any)\n\n  return (<>{functionalUpdate(children, fieldApi as any)}</>) as never\n}) satisfies FunctionComponent<FieldComponentProps<any, any, any, any, any>>\n"],"names":[],"mappings":";;;;;AA2DO,SAAS,SAWd,MAOsE;AACtE,QAAM,CAAC,QAAQ,IAAI,SAAS,MAAM;AAC1B,UAAA,MAAM,IAAI,SAAS;AAAA,MACvB,GAAG;AAAA,MACH,MAAM,KAAK;AAAA,MACX,MAAM,KAAK;AAAA,IAAA,CACZ;AAED,QAAI,QAAQ;AAEL,WAAA;AAAA,EAAA,CACR;AAED,4BAA0B,SAAS,OAAO,CAAC,QAAQ,CAAC;AAMpD,4BAA0B,MAAM;AAC9B,aAAS,OAAO,IAAI;AAAA,EAAA,CACrB;AAED;AAAA,IACE,SAAS;AAAA,IACT,KAAK,SAAS,UACV,CAAC,UAAU;AACF,aAAA,CAAC,MAAM,MAAM,OAAO,KAAK,MAAM,KAAc,EAAE,MAAM;AAAA,IAE9D,IAAA;AAAA,EAAA;AAGC,SAAA;AACT;AA4DO,MAAM,QAAS,CAUpB;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAMgB;AACR,QAAA,WAAW,SAAS,YAAmB;AAE7C,SAAW,oBAAA,UAAA,EAAA,UAAA,iBAAiB,UAAU,QAAe,EAAE,CAAA;AACzD;"}

package/dist/esm/useForm.d.ts

@@ -4,10 +4,25 @@ import { NoInfer } from '@tanstack/react-store';
 import { NodeType } from './types.js';
 
 declare module '@tanstack/form-core' {
+    /**
+     * When using `@tanstack/react-form`, the core form API is extended at type level with additional methods for React-specific functionality:
+     */
     interface FormApi<TFormData, TFormValidator> {
+        /**
+         * A React component to render form fields. With this, you can render and manage individual form fields.
+         */
         Field: FieldComponent<TFormData, TFormValidator>;
+        /**
+         * A custom React hook that provides functionalities related to individual form fields. It gives you access to field values, errors, and allows you to set or update field values.
+         */
         useField: UseField<TFormData, TFormValidator>;
+        /**
+         * A `useStore` hook that connects to the internal store of the form. It can be used to access the form's current state or any other related state information. You can optionally pass in a selector function to cherry-pick specific parts of the state
+         */
         useStore: <TSelected = NoInfer<FormState<TFormData>>>(selector?: (state: NoInfer<FormState<TFormData>>) => TSelected) => TSelected;
+        /**
+         * A `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates.
+         */
         Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {
             /**
             TypeScript versions <=5.0.4 have a bug that prevents
@@ -25,4 +40,9 @@ declare module '@tanstack/form-core' {
         }) => NodeType;
     }
 }
+/**
+ * A custom React Hook that returns an instance of the `FormApi` class.
+ *
+ * This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields
+ */
 export declare function useForm<TFormData, TFormValidator extends Validator<TFormData, unknown> | undefined = undefined>(opts?: FormOptions<TFormData, TFormValidator>): FormApi<TFormData, TFormValidator>;

package/dist/esm/useForm.js.map

@@ -1 +1 @@
-{"version":3,"file":"useForm.js","sources":["../../src/useForm.tsx"],"sourcesContent":["import { FormApi, functionalUpdate } from '@tanstack/form-core'\nimport { useStore } from '@tanstack/react-store'\nimport React, { useState } from 'react'\nimport { Field, type FieldComponent, type UseField, useField } from './useField'\nimport { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'\nimport type { NoInfer } from '@tanstack/react-store'\nimport type { FormOptions, FormState, Validator } from '@tanstack/form-core'\nimport type { NodeType } from './types'\n\ndeclare module '@tanstack/form-core' {\n  // eslint-disable-next-line no-shadow\n  interface FormApi<TFormData, TFormValidator> {\n    Field: FieldComponent<TFormData, TFormValidator>\n    useField: UseField<TFormData, TFormValidator>\n    useStore: <TSelected = NoInfer<FormState<TFormData>>>(\n      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected,\n    ) => TSelected\n    Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {\n      /**\n      TypeScript versions <=5.0.4 have a bug that prevents\n      the type of the `TSelected` generic from being inferred\n      from the return type of this method.\n\n      In these versions, `TSelected` will fall back to the default\n      type (or `unknown` if that's not defined).\n\n      @see {@link https://github.com/TanStack/form/pull/606/files#r1506715714 | This discussion on GitHub for the details}\n      @see {@link https://github.com/microsoft/TypeScript/issues/52786 | The bug report in `microsoft/TypeScript`}\n      */\n      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected\n      children: ((state: NoInfer<TSelected>) => NodeType) | NodeType\n    }) => NodeType\n  }\n}\n\nexport function useForm<\n  TFormData,\n  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,\n>(\n  opts?: FormOptions<TFormData, TFormValidator>,\n): FormApi<TFormData, TFormValidator> {\n  const [formApi] = useState(() => {\n    const api = new FormApi<TFormData, TFormValidator>(opts)\n    api.Field = function APIField(props) {\n      return (<Field {...props} form={api} />) as never\n    }\n    // eslint-disable-next-line react-hooks/rules-of-hooks\n    api.useField = (props) => useField({ ...props, form: api })\n    api.useStore = (\n      // @ts-ignore\n      selector,\n    ) => {\n      // eslint-disable-next-line react-hooks/rules-of-hooks\n      return useStore(api.store as any, selector as any) as any\n    }\n    api.Subscribe = (\n      // @ts-ignore\n      props,\n    ) => {\n      return functionalUpdate(\n        props.children,\n        // eslint-disable-next-line react-hooks/rules-of-hooks\n        useStore(api.store as any, props.selector as any),\n      ) as any\n    }\n\n    return api\n  })\n\n  useIsomorphicLayoutEffect(formApi.mount, [])\n\n  formApi.useStore((state) => state.isSubmitting)\n\n  /**\n   * formApi.update should not have any side effects. Think of it like a `useRef`\n   * that we need to keep updated every render with the most up-to-date information.\n   */\n  useIsomorphicLayoutEffect(() => {\n    formApi.update(opts)\n  })\n\n  return formApi as any\n}\n"],"names":[],"mappings":";;;;;;AAmCO,SAAS,QAId,MACoC;AACpC,QAAM,CAAC,OAAO,IAAI,SAAS,MAAM;AACzB,UAAA,MAAM,IAAI,QAAmC,IAAI;AACnD,QAAA,QAAQ,SAAS,SAAS,OAAO;AACnC,aAAS,oBAAA,OAAA,EAAO,GAAG,OAAO,MAAM,IAAK,CAAA;AAAA,IAAA;AAGnC,QAAA,WAAW,CAAC,UAAU,SAAS,EAAE,GAAG,OAAO,MAAM,IAAA,CAAK;AACtD,QAAA,WAAW,CAEb,aACG;AAEI,aAAA,SAAS,IAAI,OAAc,QAAe;AAAA,IAAA;AAE/C,QAAA,YAAY,CAEd,UACG;AACI,aAAA;AAAA,QACL,MAAM;AAAA;AAAA,QAEN,SAAS,IAAI,OAAc,MAAM,QAAe;AAAA,MAAA;AAAA,IAClD;AAGK,WAAA;AAAA,EAAA,CACR;AAEyB,4BAAA,QAAQ,OAAO,CAAA,CAAE;AAE3C,UAAQ,SAAS,CAAC,UAAU,MAAM,YAAY;AAM9C,4BAA0B,MAAM;AAC9B,YAAQ,OAAO,IAAI;AAAA,EAAA,CACpB;AAEM,SAAA;AACT;"}
+{"version":3,"file":"useForm.js","sources":["../../src/useForm.tsx"],"sourcesContent":["import { FormApi, functionalUpdate } from '@tanstack/form-core'\nimport { useStore } from '@tanstack/react-store'\nimport React, { useState } from 'react'\nimport { Field, type FieldComponent, type UseField, useField } from './useField'\nimport { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'\nimport type { NoInfer } from '@tanstack/react-store'\nimport type { FormOptions, FormState, Validator } from '@tanstack/form-core'\nimport type { NodeType } from './types'\n\ndeclare module '@tanstack/form-core' {\n  /**\n   * When using `@tanstack/react-form`, the core form API is extended at type level with additional methods for React-specific functionality:\n   */\n  // eslint-disable-next-line no-shadow\n  interface FormApi<TFormData, TFormValidator> {\n    /**\n     * A React component to render form fields. With this, you can render and manage individual form fields.\n     */\n    Field: FieldComponent<TFormData, TFormValidator>\n    /**\n     * A custom React hook that provides functionalities related to individual form fields. It gives you access to field values, errors, and allows you to set or update field values.\n     */\n    useField: UseField<TFormData, TFormValidator>\n    /**\n     * A `useStore` hook that connects to the internal store of the form. It can be used to access the form's current state or any other related state information. You can optionally pass in a selector function to cherry-pick specific parts of the state\n     */\n    useStore: <TSelected = NoInfer<FormState<TFormData>>>(\n      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected,\n    ) => TSelected\n    /**\n     * A `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates.\n     */\n    Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {\n      /**\n      TypeScript versions <=5.0.4 have a bug that prevents\n      the type of the `TSelected` generic from being inferred\n      from the return type of this method.\n\n      In these versions, `TSelected` will fall back to the default\n      type (or `unknown` if that's not defined).\n\n      @see {@link https://github.com/TanStack/form/pull/606/files#r1506715714 | This discussion on GitHub for the details}\n      @see {@link https://github.com/microsoft/TypeScript/issues/52786 | The bug report in `microsoft/TypeScript`}\n      */\n      selector?: (state: NoInfer<FormState<TFormData>>) => TSelected\n      children: ((state: NoInfer<TSelected>) => NodeType) | NodeType\n    }) => NodeType\n  }\n}\n\n/**\n * A custom React Hook that returns an instance of the `FormApi` class.\n *\n * This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields\n */\nexport function useForm<\n  TFormData,\n  TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,\n>(\n  opts?: FormOptions<TFormData, TFormValidator>,\n): FormApi<TFormData, TFormValidator> {\n  const [formApi] = useState(() => {\n    const api = new FormApi<TFormData, TFormValidator>(opts)\n    api.Field = function APIField(props) {\n      return (<Field {...props} form={api} />) as never\n    }\n    // eslint-disable-next-line react-hooks/rules-of-hooks\n    api.useField = (props) => useField({ ...props, form: api })\n    api.useStore = (\n      // @ts-ignore\n      selector,\n    ) => {\n      // eslint-disable-next-line react-hooks/rules-of-hooks\n      return useStore(api.store as any, selector as any) as any\n    }\n    api.Subscribe = (\n      // @ts-ignore\n      props,\n    ) => {\n      return functionalUpdate(\n        props.children,\n        // eslint-disable-next-line react-hooks/rules-of-hooks\n        useStore(api.store as any, props.selector as any),\n      ) as any\n    }\n\n    return api\n  })\n\n  useIsomorphicLayoutEffect(formApi.mount, [])\n\n  formApi.useStore((state) => state.isSubmitting)\n\n  /**\n   * formApi.update should not have any side effects. Think of it like a `useRef`\n   * that we need to keep updated every render with the most up-to-date information.\n   */\n  useIsomorphicLayoutEffect(() => {\n    formApi.update(opts)\n  })\n\n  return formApi as any\n}\n"],"names":[],"mappings":";;;;;;AAuDO,SAAS,QAId,MACoC;AACpC,QAAM,CAAC,OAAO,IAAI,SAAS,MAAM;AACzB,UAAA,MAAM,IAAI,QAAmC,IAAI;AACnD,QAAA,QAAQ,SAAS,SAAS,OAAO;AACnC,aAAS,oBAAA,OAAA,EAAO,GAAG,OAAO,MAAM,IAAK,CAAA;AAAA,IAAA;AAGnC,QAAA,WAAW,CAAC,UAAU,SAAS,EAAE,GAAG,OAAO,MAAM,IAAA,CAAK;AACtD,QAAA,WAAW,CAEb,aACG;AAEI,aAAA,SAAS,IAAI,OAAc,QAAe;AAAA,IAAA;AAE/C,QAAA,YAAY,CAEd,UACG;AACI,aAAA;AAAA,QACL,MAAM;AAAA;AAAA,QAEN,SAAS,IAAI,OAAc,MAAM,QAAe;AAAA,MAAA;AAAA,IAClD;AAGK,WAAA;AAAA,EAAA,CACR;AAEyB,4BAAA,QAAQ,OAAO,CAAA,CAAE;AAE3C,UAAQ,SAAS,CAAC,UAAU,MAAM,YAAY;AAM9C,4BAA0B,MAAM;AAC9B,YAAQ,OAAO,IAAI;AAAA,EAAA,CACpB;AAEM,SAAA;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-form",
-  "version": "0.23.2",
+  "version": "0.24.0",
   "description": "Powerful, type-safe forms for React.",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -57,7 +57,7 @@
   "dependencies": {
     "@tanstack/react-store": "^0.5.0",
     "decode-formdata": "^0.7.5",
-    "@tanstack/form-core": "0.23.2"
+    "@tanstack/form-core": "0.24.0"
   },
   "peerDependencies": {
     "react": "^17.0.0 || ^18.0.0"

package/src/types.ts

@@ -6,6 +6,9 @@ import type {
 } from '@tanstack/form-core'
 import type { FunctionComponent } from 'react'
 
+/**
+ * The field options.
+ */
 export type UseFieldOptions<
   TParentData,
   TName extends DeepKeys<TParentData>,

package/src/useField.tsx

@@ -6,6 +6,9 @@ import type { NodeType, UseFieldOptions } from './types'
 import type { DeepKeys, DeepValue, Validator } from '@tanstack/form-core'
 
 declare module '@tanstack/form-core' {
+  /**
+   * When using `@tanstack/react-form`, the core field API is extended at type level with additional methods for React-specific functionality:
+   */
   // eslint-disable-next-line no-shadow
   interface FieldApi<
     TParentData,
@@ -18,10 +21,18 @@ declare module '@tanstack/form-core' {
       | undefined = undefined,
     TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
   > {
+    /**
+     * A pre-bound and type-safe sub-field component using this field as a root.
+     */
     Field: FieldComponent<TParentData, TFormValidator>
   }
 }
 
+/**
+ * A type representing a hook for using a field in a form with the given form data type.
+ *
+ * A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field.
+ */
 export type UseField<
   TParentData,
   TFormValidator extends
@@ -40,6 +51,12 @@ export type UseField<
   >,
 ) => FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>
 
+/**
+ * A hook for managing a field in a form.
+ * @param opts An object with field options.
+ *
+ * @returns The `FieldApi` instance for the specified field.
+ */
 export function useField<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -93,6 +110,9 @@ export function useField<
   return fieldApi as never
 }
 
+/**
+ * @param children A render function that takes a field API instance and returns a React element.
+ */
 type FieldComponentProps<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -115,6 +135,9 @@ type FieldComponentProps<
   ) => NodeType
 } & UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>
 
+/**
+ * A type alias representing a field component for a specific form data type.
+ */
 export type FieldComponent<
   TParentData,
   TFormValidator extends
@@ -140,6 +163,11 @@ export type FieldComponent<
   'form'
 >) => NodeType
 
+/**
+ * A function component that takes field options and a render function as children and returns a React component.
+ *
+ * The `Field` component uses the `useField` hook internally to manage the field instance.
+ */
 export const Field = (<
   TParentData,
   TName extends DeepKeys<TParentData>,

package/src/useForm.tsx

@@ -8,13 +8,28 @@ import type { FormOptions, FormState, Validator } from '@tanstack/form-core'
 import type { NodeType } from './types'
 
 declare module '@tanstack/form-core' {
+  /**
+   * When using `@tanstack/react-form`, the core form API is extended at type level with additional methods for React-specific functionality:
+   */
   // eslint-disable-next-line no-shadow
   interface FormApi<TFormData, TFormValidator> {
+    /**
+     * A React component to render form fields. With this, you can render and manage individual form fields.
+     */
     Field: FieldComponent<TFormData, TFormValidator>
+    /**
+     * A custom React hook that provides functionalities related to individual form fields. It gives you access to field values, errors, and allows you to set or update field values.
+     */
     useField: UseField<TFormData, TFormValidator>
+    /**
+     * A `useStore` hook that connects to the internal store of the form. It can be used to access the form's current state or any other related state information. You can optionally pass in a selector function to cherry-pick specific parts of the state
+     */
     useStore: <TSelected = NoInfer<FormState<TFormData>>>(
       selector?: (state: NoInfer<FormState<TFormData>>) => TSelected,
     ) => TSelected
+    /**
+     * A `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates.
+     */
     Subscribe: <TSelected = NoInfer<FormState<TFormData>>>(props: {
       /**
       TypeScript versions <=5.0.4 have a bug that prevents
@@ -33,6 +48,11 @@ declare module '@tanstack/form-core' {
   }
 }
 
+/**
+ * A custom React Hook that returns an instance of the `FormApi` class.
+ *
+ * This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields
+ */
 export function useForm<
   TFormData,
   TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,

package/src/tests/useField.test-d.tsx

@@ -1,110 +0,0 @@
-import * as React from 'react'
-import { assertType, it } from 'vitest'
-import { useForm } from '../useForm'
-
-it('should type state.value properly', () => {
-  function Comp() {
-    const form = useForm({
-      defaultValues: {
-        firstName: 'test',
-        age: 84,
-      },
-    } as const)
-
-    return (
-      <>
-        <form.Field
-          name="firstName"
-          children={(field) => {
-            assertType<'test'>(field.state.value)
-            return null
-          }}
-        />
-        <form.Field
-          name="age"
-          children={(field) => {
-            assertType<84>(field.state.value)
-            return null
-          }}
-        />
-      </>
-    )
-  }
-})
-
-it('should type onChange properly', () => {
-  function Comp() {
-    const form = useForm({
-      defaultValues: {
-        firstName: 'test',
-        age: 84,
-      },
-    } as const)
-
-    return (
-      <>
-        <form.Field
-          name="firstName"
-          validators={{
-            onChange: ({ value }) => {
-              assertType<'test'>(value)
-              return null
-            },
-          }}
-          children={() => null}
-        />
-        <form.Field
-          name="age"
-          validators={{
-            onChange: ({ value }) => {
-              assertType<84>(value)
-              return null
-            },
-          }}
-          children={() => null}
-        />
-      </>
-    )
-  }
-})
-
-it('should type array subfields', () => {
-  type FormDefinition = {
-    nested: {
-      people: {
-        name: string
-        age: number
-      }[]
-    }
-  }
-
-  function App() {
-    const form = useForm({
-      defaultValues: {
-        nested: {
-          people: [],
-        },
-      } as FormDefinition,
-      onSubmit({ value }) {
-        alert(JSON.stringify(value))
-      },
-    })
-
-    return (
-      <form.Field name="nested.people" mode="array">
-        {(field) =>
-          field.state.value.map((_, i) => (
-            <form.Field key={i} name={`nested.people[${i}].name`}>
-              {(subField) => (
-                <input
-                  value={subField.state.value}
-                  onChange={(e) => subField.handleChange(e.target.value)}
-                />
-              )}
-            </form.Field>
-          ))
-        }
-      </form.Field>
-    )
-  }
-})