TanStack · crutchcorn · Jul 7, 2024 · Jul 7, 2024 · Jul 7, 2024 · Jul 7, 2024
diff --git a/examples/react/custom-component-wrapper/.eslintrc.cjs b/examples/react/custom-component-wrapper/.eslintrc.cjs
@@ -0,0 +1,11 @@
+// @ts-check
+
+/** @type {import('eslint').Linter.Config} */
+const config = {
+  extends: ['plugin:react/recommended', 'plugin:react-hooks/recommended'],
+  rules: {
+    'react/no-children-prop': 'off',
+  },
+}
+
+module.exports = config
diff --git a/examples/react/custom-component-wrapper/.gitignore b/examples/react/custom-component-wrapper/.gitignore
@@ -0,0 +1,27 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+
+pnpm-lock.yaml
+yarn.lock
+package-lock.json
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/examples/react/custom-component-wrapper/README.md b/examples/react/custom-component-wrapper/README.md
@@ -0,0 +1,6 @@
+# Example
+
+To run this example:
+
+- `npm install`
+- `npm run dev`
diff --git a/examples/react/custom-component-wrapper/index.html b/examples/react/custom-component-wrapper/index.html
@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" type="image/svg+xml" href="/emblem-light.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+
+    <title>TanStack Form React Simple Example App</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>
diff --git a/examples/react/custom-component-wrapper/package.json b/examples/react/custom-component-wrapper/package.json
@@ -0,0 +1,34 @@
+{
+  "name": "@tanstack/form-example-react-custom-component-wrapper",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port=3001",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@tanstack/react-form": "^0.25.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "vite": "^5.1.4"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}
diff --git a/examples/react/custom-component-wrapper/public/emblem-light.svg b/examples/react/custom-component-wrapper/public/emblem-light.svg
diff --git a/examples/react/custom-component-wrapper/src/index.tsx b/examples/react/custom-component-wrapper/src/index.tsx
@@ -0,0 +1,132 @@
+import * as React from 'react'
+import { createRoot } from 'react-dom/client'
+import { useForm } from '@tanstack/react-form'
+import type {
+  DeepKeyValueName,
+  FieldOptions,
+  ReactFormApi,
+} from '@tanstack/react-form'
+
+/**
+ * Export these components to your design system or a dedicated component location
+ */
+interface TextInputFieldProps<
+  TFormData extends unknown,
+  TName extends DeepKeyValueName<TFormData, string>,
+> extends FieldOptions<TFormData, TName> {
+  form: ReactFormApi<TFormData, any>
+  // Your custom props
+  label: string
+}
+
+function TextInputField<
+  TFormData extends unknown,
+  TName extends DeepKeyValueName<TFormData, string>,
+>({ form, name, label, ...fieldProps }: TextInputFieldProps<TFormData, TName>) {
+  return (
+    // Manually type-cast form.Field to work around this issue:
+    // https://twitter.com/crutchcorn/status/1809827621485900049
+    <form.Field<TName, any, any>
+      {...fieldProps}
+      name={name}
+      children={(field) => {
+        return (
+          <div style={{ marginBottom: '1rem' }}>
+            <div>
+              <label htmlFor={field.name}>{label}</label>
+            </div>
+            <input
+              id={field.name}
+              name={field.name}
+              value={field.state.value}
+              onBlur={field.handleBlur}
+              onChange={(e) => field.handleChange(e.target.value)}
+            />
+            {field.state.meta.isValidating ? (
+              <div style={{ color: 'gray' }}>Validating...</div>
+            ) : null}
+            {field.state.meta.isTouched && field.state.meta.errors.length ? (
+              <div style={{ color: 'red' }}>
+                {field.state.meta.errors.join(', ')}
+              </div>
+            ) : null}
+          </div>
+        )
+      }}
+    />
+  )
+}
+
+function SubmitButton({ form }: { form: ReactFormApi<any, any> }) {
+  return (
+    <form.Subscribe
+      selector={(state) => [state.canSubmit, state.isSubmitting]}
+      children={([canSubmit, isSubmitting]) => (
+        <>
+          <button type="submit" disabled={!canSubmit}>
+            {isSubmitting ? '...' : 'Submit'}
+          </button>
+        </>
+      )}
+    />
+  )
+}
+
+/**
+ * Then use it in your application
+ */
+export default function App() {
+  const form = useForm({
+    defaultValues: {
+      firstName: '',
+      age: 0,
+    },
+    onSubmit: async ({ value }) => {
+      // Do something with form data
+      console.log(value)
+    },
+  })
+
+  return (
+    <div>
+      <h1>Wrapped Fields Form Example</h1>
+      <form
+        onSubmit={(e) => {
+          e.preventDefault()
+          e.stopPropagation()
+          form.handleSubmit()
+        }}
+      >
+        {/* A type-safe, wrapped field component*/}
+        <TextInputField
+          label={'First name:'}
+          form={form}
+          name="firstName"
+          validators={{
+            onChangeAsync: async ({ value }) => {
+              await new Promise((resolve) => setTimeout(resolve, 1000))
+              if (value.length < 3) {
+                return 'Name must be at least 3 characters long'
+              }
+              return undefined
+            },
+          }}
+        />
+        {/* Correctly throws a warning when the wrong data type is passed */}
+        <TextInputField label={'Age:'} form={form} name="age" />
+        <SubmitButton form={form} />
+        <button type="reset" onClick={() => form.reset()}>
+          Reset
+        </button>
+      </form>
+    </div>
+  )
+}
+
+const rootElement = document.getElementById('root')!
+
+createRoot(rootElement).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
diff --git a/examples/react/custom-component-wrapper/tsconfig.json b/examples/react/custom-component-wrapper/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "jsx": "react",
+    "noEmit": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "lib": ["DOM", "DOM.Iterable", "ES2020"]
+  }
+}
diff --git a/packages/form-core/src/util-types.ts b/packages/form-core/src/util-types.ts
@@ -111,7 +111,6 @@ export type DeepValue<
   TValue,
   // A string representing the path of the property we're trying to access
   TAccessor,
-  TNullable extends boolean = IsNullable<TValue>,
 > =
   // If TValue is any it will recurse forever, this terminates the recursion
   unknown extends TValue
@@ -138,9 +137,21 @@ export type DeepValue<
             : TAccessor extends `${infer TBefore}.${infer TAfter}`
               ? DeepValue<DeepValue<TValue, TBefore>, TAfter>
               : TAccessor extends string
-                ? TNullable extends true
+                ? IsNullable<TValue> extends true
                   ? Nullable<TValue[TAccessor]>
                   : TValue[TAccessor]
                 : never
         : // Do not allow `TValue` to be anything else
           never
+
+type SelfKeys<T> = {
+  [K in keyof T]: K
+}[keyof T]
+
+// Utility type to narrow allowed TName values to only specific types
+// IE: DeepKeyValueName<{ foo: string; bar: number }, string> = 'foo'
+export type DeepKeyValueName<TFormData, TField> = SelfKeys<{
+  [K in DeepKeys<TFormData> as DeepValue<TFormData, K> extends TField
+    ? K
+    : never]: K
+}>
diff --git a/packages/form-core/tests/util-types.test-d.ts b/packages/form-core/tests/util-types.test-d.ts
@@ -1,5 +1,5 @@
 import { assertType } from 'vitest'
-import type { DeepKeys, DeepValue } from '../src/index'
+import { DeepKeys, DeepKeyValueName, DeepValue } from '../src/index'
 
 /**
  * Properly recognizes that `0` is not an object and should not have subkeys
@@ -169,3 +169,30 @@ type DoubleDeepArray = DeepValue<
 >
 
 assertType<string>(0 as never as DoubleDeepArray)
+
+type FooBarOther = {
+  foo: string
+  bar: string
+  other: number
+}
+
+type StringFromFooBar = DeepKeyValueName<FooBarOther, string>
+
+assertType<'foo' | 'bar'>(0 as never as StringFromFooBar)
+
+type DeepFooBarOther = {
+  foo: string
+  bar: string
+  other: number
+  one: {
+    foo: string
+    bar: string
+    other: number
+  }
+}
+
+type StringFromDeepFooBar = DeepKeyValueName<DeepFooBarOther, string>
+
+assertType<'foo' | 'bar' | 'one.foo' | 'one.bar'>(
+  0 as never as StringFromDeepFooBar,
+)
diff --git a/packages/react-form/src/index.ts b/packages/react-form/src/index.ts
@@ -1,6 +1,6 @@
 export * from '@tanstack/form-core'
 
-export { useForm } from './useForm'
+export { useForm, type ReactFormApi } from './useForm'
 
 export type { UseField, FieldComponent } from './useField'
 export { useField, Field } from './useField'

diff --git a/packages/react-form/src/useField.tsx b/packages/react-form/src/useField.tsx
@@ -5,18 +5,6 @@ import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
 import type { NodeType, UseFieldOptions } from './types'
 import type { DeepKeys, DeepValue, Validator } from '@tanstack/form-core'
 
-interface ReactFieldApi<
-  TParentData,
-  TFormValidator extends
-    | Validator<TParentData, unknown>
-    | undefined = undefined,
-> {
-  /**
-   * 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.
  *
@@ -66,18 +54,11 @@ export function useField<
   >,
 ) {
   const [fieldApi] = useState(() => {
-    const api = new FieldApi({
+    return new FieldApi({
       ...opts,
       form: opts.form,
       name: opts.name,
     })
-
-    const extendedApi: typeof api & ReactFieldApi<TParentData, TFormValidator> =
-      api as never
-
-    extendedApi.Field = Field as never
-
-    return extendedApi
   })
 
   useIsomorphicLayoutEffect(fieldApi.mount, [fieldApi])

diff --git a/packages/react-form/src/useForm.tsx b/packages/react-form/src/useForm.tsx
@@ -10,7 +10,7 @@ import type { NodeType } from './types'
 /**
  * Fields that are added onto the `FormAPI` from `@tanstack/form-core` and returned from `useForm`
  */
-interface ReactFormApi<
+export interface ReactFormApi<
   TFormData,
   TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
 > {