docs: improve docs, add disclaimer where docs are outdated (#412)

docs/guides/basic-concepts.md

@@ -5,6 +5,8 @@ title: Basic Concepts and Terminology
 
 # Basic Concepts and Terminology
 
+> Some of these docs may be inaccurate due to an API shift in `0.11.0`. If you're interested in helping us fix these issues, please [join our Discord](https://tlinz.com/discord) and reach out in the `#form` channel.
+
 This page introduces the basic concepts and terminology used in the @tanstack/react-form library. Familiarizing yourself with these concepts will help you better understand and work with the library.
 
 ## Form Factory

docs/guides/important-defaults.md

@@ -3,6 +3,8 @@ id: important-defaults
 title: Important Defaults
 ---
 
+> Some of these docs may be inaccurate due to an API shift in `0.11.0`. If you're interested in helping us fix these issues, please [join our Discord](https://tlinz.com/discord) and reach out in the `#form` channel.
+
 Out of the box, TanStack Form is configured with **aggressive but sane** defaults. **Sometimes these defaults can catch new users off guard or make learning/debugging difficult if they are unknown by the user.** Keep them in mind as you continue to learn and use TanStack Form:
 
 - Core

docs/installation.md

@@ -3,14 +3,11 @@ id: installation
 title: Installation
 ---
 
-TanStack Form is compatible with various front-end frameworks, including React, Solid, Svelte and Vue. To use TanStack Form with your desired framework, install the corresponding adapter via NPM
+While the core of TanStack Form is framework-agnostic and will be compatible with various front-end frameworks in the future, we only support React today.
+To use TanStack Form with React, install the adapter via NPM
 
 ```bash
 $ npm i @tanstack/react-form
-# or
-$ pnpm add @tanstack/solid-form
-# or
-$ yarn add @tanstack/svelte-form
 ```
 
 > Depending on your environment, you might need to add polyfills. If you want to support older browsers, you need to transpile the library from `node_modules` yourselves.

docs/overview.md

@@ -26,19 +26,20 @@ In the example below, you can see TanStack Form in action with the React framewo
 [Open in CodeSandbox](https://codesandbox.io/s/github/tannerlinsley/react-form/tree/main/examples/react/simple)
 
 ```tsx
-import React from 'react'
+import React from "react";
-import ReactDOM from 'react-dom/client'
+import ReactDOM from "react-dom/client";
-import { useForm, FieldApi } from '@tanstack/react-form'
+import { useForm } from "@tanstack/react-form";
+import type { FieldApi } from "@tanstack/react-form";
 
 function FieldInfo({ field }: { field: FieldApi<any, any> }) {
   return (
     <>
       {field.state.meta.touchedError ? (
         <em>{field.state.meta.touchedError}</em>
-      ) : null}{' '}
+      ) : null}{" "}
-      {field.state.meta.isValidating ? 'Validating...' : null}
+      {field.state.meta.isValidating ? "Validating..." : null}
     </>
-  )
+  );
 }
 
 export default function App() {
@@ -46,43 +47,51 @@ export default function App() {
     // Memoize your default values to prevent re-renders
     defaultValues: React.useMemo(
       () => ({
-        firstName: '',
+        firstName: "",
-        lastName: '',
+        lastName: "",
       }),
       [],
     ),
     onSubmit: async (values) => {
       // Do something with form data
-      console.log(values)
+      console.log(values);
     },
-  })
+  });
 
   return (
     <div>
       <h1>Simple Form Example</h1>
       {/* A pre-bound form component */}
-      <form.Form>
+      <form.Provider>
+        <form {...form.getFormProps()}>
           <div>
             {/* A type-safe and pre-bound field component*/}
             <form.Field
               name="firstName"
-            validate={(value) => !value && 'A first name is required'}
+              onChange={(value) =>
-            validateAsyncOn="change"
+                !value
-            validateAsyncDebounceMs={500}
+                  ? "A first name is required"
-            validateAsync={async (value) => {
+                  : value.length < 3
-              await new Promise((resolve) => setTimeout(resolve, 1000))
+                  ? "First name must be at least 3 characters"
+                  : undefined
+              }
+              onChangeAsyncDebounceMs={500}
+              onChangeAsync={async (value) => {
+                await new Promise((resolve) => setTimeout(resolve, 1000));
                 return (
-                value.includes('error') && 'No "error" allowed in first name'
+                  value.includes("error") && 'No "error" allowed in first name'
-              )
+                );
               }}
-            children={(field) => (
+              children={(field) => {
                 // Avoid hasty abstractions. Render props are great!
+                return (
                   <>
                     <label htmlFor={field.name}>First Name:</label>
                     <input name={field.name} {...field.getInputProps()} />
                     <FieldInfo field={field} />
                   </>
-            )}
+                );
+              }}
             />
           </div>
           <div>
@@ -101,17 +110,19 @@ export default function App() {
             selector={(state) => [state.canSubmit, state.isSubmitting]}
             children={([canSubmit, isSubmitting]) => (
               <button type="submit" disabled={!canSubmit}>
-              {isSubmitting ? '...' : 'Submit'}
+                {isSubmitting ? "..." : "Submit"}
               </button>
             )}
           />
-      </form.Form>
+        </form>
+      </form.Provider>
     </div>
-  )
+  );
 }
 
-const rootElement = document.getElementById('root')!
+const rootElement = document.getElementById("root")!;
-ReactDOM.createRoot(rootElement).render(<App />)
+
+ReactDOM.createRoot(rootElement).render(<App />);
 ```
 
 ## You talked me into it, so what now?

docs/reference/fieldApi.md

@@ -5,6 +5,8 @@ title: Field API
 
 ### Creating a new FieldApi Instance
 
+> Some of these docs may be inaccurate due to an API shift in `0.11.0`. If you're interested in helping us fix these issues, please [join our Discord](https://tlinz.com/discord) and reach out in the `#form` channel.
+
 Normally, you will not need to create a new `FieldApi` instance directly. Instead, you will use a framework hook/function like `useField` or `createField` to create a new instance for you that utilizes your frameworks reactivity model. However, if you need to create a new instance manually, you can do so by calling the `new FieldApi` constructor.
 
 ```tsx

docs/reference/formApi.md

@@ -5,6 +5,8 @@ title: Form API
 
 ### Creating a new FormApi Instance
 
+> Some of these docs may be inaccurate due to an API shift in `0.11.0`. If you're interested in helping us fix these issues, please [join our Discord](https://tlinz.com/discord) and reach out in the `#form` channel.
+
 Normally, you will not need to create a new `FormApi` instance directly. Instead, you will use a framework hook/function like `useForm` or `createForm` to create a new instance for you that utilizes your frameworks reactivity model. However, if you need to create a new instance manually, you can do so by calling the `new FormApi` constructor.
 
 ```tsx

examples/react/simple/package.json

@@ -8,7 +8,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@tanstack/react-form": "0.0.11",
+    "@tanstack/react-form": "0.0.12",
     "axios": "^0.26.1",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",

examples/react/simple/src/index.tsx

@@ -1,28 +1,8 @@
 import React from "react";
 import ReactDOM from "react-dom/client";
-import { createFormFactory } from "@tanstack/react-form";
+import { useForm } from "@tanstack/react-form";
 import type { FieldApi } from "@tanstack/react-form";
 
-type Person = {
-  firstName: string;
-  lastName: string;
-  hobbies: Hobby[];
-};
-
-type Hobby = {
-  name: string;
-  description: string;
-  yearsOfExperience: number;
-};
-
-const formFactory = createFormFactory<Person>({
-  defaultValues: {
-    firstName: "",
-    lastName: "",
-    hobbies: [],
-  },
-});
-
 function FieldInfo({ field }: { field: FieldApi<any, any> }) {
   return (
     <>
@@ -35,18 +15,23 @@ function FieldInfo({ field }: { field: FieldApi<any, any> }) {
 }
 
 export default function App() {
-  const form = formFactory.useForm({
+  const form = useForm({
-    onSubmit: async (values, formApi) => {
+    // Memoize your default values to prevent re-renders
+    defaultValues: React.useMemo(
+      () => ({
+        firstName: "",
+        lastName: "",
+      }),
+      [],
+    ),
+    onSubmit: async (values) => {
       // Do something with form data
       console.log(values);
     },
   });
 
-  const [count, setCount] = React.useState(0);
-
   return (
     <div>
-      <button onClick={() => setCount((prev) => prev + 1)}>{count}</button>
       <h1>Simple Form Example</h1>
       {/* A pre-bound form component */}
       <form.Provider>
@@ -62,6 +47,7 @@ export default function App() {
                   ? "First name must be at least 3 characters"
                   : undefined
               }
+              onChangeAsyncDebounceMs={500}
               onChangeAsync={async (value) => {
                 await new Promise((resolve) => setTimeout(resolve, 1000));
                 return (
@@ -72,121 +58,33 @@ export default function App() {
                 // Avoid hasty abstractions. Render props are great!
                 return (
                   <>
-                    <input {...field.getInputProps()} />
+                    <label htmlFor={field.name}>First Name:</label>
+                    <input name={field.name} {...field.getInputProps()} />
                     <FieldInfo field={field} />
                   </>
                 );
               }}
             />
           </div>
-          {/* <div>
+          <div>
             <form.Field
               name="lastName"
               children={(field) => (
                 <>
-                  <input {...field.getInputProps()} />
+                  <label htmlFor={field.name}>Last Name:</label>
+                  <input name={field.name} {...field.getInputProps()} />
                   <FieldInfo field={field} />
                 </>
               )}
             />
           </div>
-          <div>
-            <form.Field
-              name="hobbies"
-              mode="array"
-              children={(hobbiesField) => (
-                <div>
-                  Hobbies
-                  <div
-                    style={{
-                      paddingLeft: "1rem",
-                      display: "flex",
-                      flexDirection: "column",
-                      gap: "1rem",
-                    }}
-                  >
-                    {!hobbiesField.state.value.length
-                      ? "No hobbies found."
-                      : hobbiesField.state.value.map((_, i) => (
-                          <div
-                            key={i}
-                            style={{
-                              borderLeft: "2px solid gray",
-                              paddingLeft: ".5rem",
-                            }}
-                          >
-                            <hobbiesField.Field
-                              index={i}
-                              name="name"
-                              children={(field) => {
-                                return (
-                                  <div>
-                                    <label htmlFor={field.name}>Name:</label>
-                                    <input
-                                      name={field.name}
-                                      {...field.getInputProps()}
-                                    />
-                                    <button
-                                      type="button"
-                                      onClick={() =>
-                                        hobbiesField.removeValue(i)
-                                      }
-                                    >
-                                      X
-                                    </button>
-                                    <FieldInfo field={field} />
-                                  </div>
-                                );
-                              }}
-                            />
-                            <hobbiesField.Field
-                              index={i}
-                              name="description"
-                              children={(field) => {
-                                return (
-                                  <div>
-                                    <label htmlFor={field.name}>
-                                      Description:
-                                    </label>
-                                    <input
-                                      name={field.name}
-                                      {...field.getInputProps()}
-                                    />
-                                    <FieldInfo field={field} />
-                                  </div>
-                                );
-                              }}
-                            />
-                          </div>
-                        ))}
-                  </div>
-                  <button
-                    type="button"
-                    onClick={() =>
-                      hobbiesField.pushValue({
-                        name: "",
-                        description: "",
-                        yearsOfExperience: 0,
-                      })
-                    }
-                  >
-                    Add hobby
-                  </button>
-                </div>
-              )}
-            />
-          </div> */}
           <form.Subscribe
-            {...{
+            selector={(state) => [state.canSubmit, state.isSubmitting]}
-              // TS bug - inference isn't working with props, so use object
+            children={([canSubmit, isSubmitting]) => (
-              selector: (state) =>
-                [state.canSubmit, state.isSubmitting] as const,
-              children: ([canSubmit, isSubmitting]) => (
               <button type="submit" disabled={!canSubmit}>
                 {isSubmitting ? "..." : "Submit"}
               </button>
-              ),
+            )}
-            }}
           />
         </form>
       </form.Provider>