LukeParke/form
1
0
Fork 0
mirror of https://github.com/LukeHagar/form.git synced 2025-12-06 12:27:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Corbin Crutchley
2023-08-29 15:08:25 -07:00
committed by GitHub
parent 27dec1f9a9
commit c392c6100d
9 changed files with 2119 additions and 559 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/guides/basic-concepts.md
View File

@@ -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

2
docs/guides/important-defaults.md
View File

@@ -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

7
docs/installation.md
View File

@@ -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.

61
docs/overview.md
View File

@@ -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 ReactDOM from 'react-dom/client'
import { useForm, FieldApi } from '@tanstack/react-form'
import React from "react";
import ReactDOM from "react-dom/client";
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}{' '}
{field.state.meta.isValidating ? 'Validating...' : null}
) : 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: '',
lastName: '',
firstName: "",
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'}
validateAsyncOn="change"
validateAsyncDebounceMs={500}
validateAsync={async (value) => {
await new Promise((resolve) => setTimeout(resolve, 1000))
onChange={(value) =>
!value
? "A first name is required"
: value.length < 3
? "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')!
ReactDOM.createRoot(rootElement).render(<App />)
const rootElement = document.getElementById("root")!;
ReactDOM.createRoot(rootElement).render(<App />);
```
## You talked me into it, so what now?

2
docs/reference/fieldApi.md
View File

@@ -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

2
docs/reference/formApi.md
View File

@@ -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

2
examples/react/simple/package.json
View File

@@ -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",

142
examples/react/simple/src/index.tsx
View File

@@ -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({
onSubmit: async (values, formApi) => {
const form = useForm({
// 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
{...{
// TS bug - inference isn't working with props, so use object
selector: (state) =>
[state.canSubmit, state.isSubmitting] as const,
children: ([canSubmit, isSubmitting]) => (
selector={(state) => [state.canSubmit, state.isSubmitting]}
children={([canSubmit, isSubmitting]) => (
<button type="submit" disabled={!canSubmit}>
{isSubmitting ? "..." : "Submit"}
</button>
),
}}
)}
/>
</form>
</form.Provider>

2390
pnpm-lock.yaml generated
View File

File diff suppressed because it is too large Load Diff