+ 
+
+
+ Loadingā¦
+ } @else if (userQuery.isError()) { +Could not load the user.
+ } @else { + + } + `, +}) +export class UserPageComponent { + private route = inject(ActivatedRoute) + private userId = this.route.snapshot.paramMap.get('userId')! + + userQuery = injectQuery(() => ({ + queryKey: ['user', this.userId], + queryFn: async (): Promise{{ formErrorMap().onDynamic?.firstName }}
`, -}) -export class AppComponent { - form = injectForm({ - // ... - validationLogic: revalidateLogic(), - validators: { - onDynamic: ({ value }) => { - if (!value.firstName) { - return { firstName: 'A first name is required' } - } - return undefined - }, - }, - }) - - formErrorMap = injectStore(this.form, (state) => state.errorMap) -} -``` - -## Usage with Other Validation Logic - -You can use `onDynamic` validation alongside other validation logic, such as `onChange` or `onBlur`. - -```angular-ts -import { Component } from '@angular/core' -import { - TanStackField, - injectForm, - injectStore, - revalidateLogic, -} from '@tanstack/angular-form' - -@Component({ - selector: 'app-root', - standalone: true, - imports: [TanStackField], - template: ` -{{ formErrorMap().onChange?.firstName }}
-{{ formErrorMap().onDynamic?.lastName }}
-Validating...
- } -Validating...
- } -Validating...
- } - `, -}) -export class AppTextField { - label = input.requiredCould not load.
` + if (!this.form) return html`Loadingā¦
` + return html`` + } +} +``` + +This is useful when no form state is needed during loading. Creating a fresh +editor for a different record also makes record changes explicit. + +## Create the form before data arrives + +Provide a static, shape-complete fallback, then call `form.update(...)` when +the query result changes. Keep option creation in one function so callbacks and +validation settings remain consistent. + +```ts +import { TanStackFormController, formOptions } from '@tanstack/lit-form' + +const emptyUser: User = { + firstName: '', + lastName: '', +} + +class UserEditor extends LitElement { + private form = new TanStackFormController(this, this.options(emptyUser)) + + private options(defaultValues: User) { + return formOptions({ + defaultValues, + onSubmit: async ({ value }) => { + await saveUser(value) + }, + }) + } + + connectedCallback() { + super.connectedCallback() + void loadUser().then((user) => { + this.form.update(this.options(user)) + this.requestUpdate() + }) + } +} +``` + +When loaded data replaces the fallback, TanStack Form applies the new defaults +to untouched fields while preserving fields the user already touched. You can +hide the fields during loading or render the empty form immediately. + +The repository's `examples/lit/query-integration` example demonstrates this +pattern with `QueryObserver` from TanStack Query Core. + +## Background refetches and record changes + +`defaultValues` establish the baseline; they are not a fully controlled +`values` property. Later `form.update(...)` calls preserve touched fields. + +If a background refetch arrives while a user is editing, decide whether to keep +local edits, prompt before replacing them, or deliberately call +`form.api.reset(nextValues)`. Do not overwrite in-progress input merely because +a query refreshed. + +When switching records, create a fresh editor element/controller or explicitly +reset the existing form. Otherwise, touched values from the previous record can +be preserved when new defaults arrive. diff --git a/docs/framework/lit/guides/basic-concepts.md b/docs/framework/lit/guides/basic-concepts.md deleted file mode 100644 index efc3a7c607..0000000000 --- a/docs/framework/lit/guides/basic-concepts.md +++ /dev/null @@ -1,132 +0,0 @@ ---- -id: basic-concepts -title: Basic Concepts and Terminology ---- - -This page introduces the basic concepts and terminology used in the `@tanstack/lit-form` library. Familiarizing yourself with these concepts will help you better understand and work with the library and its usage with Lit. - -## Form Options - -You can create options for your form so that it can be shared between multiple forms by using the `formOptions` function. - -For Example: - -```tsx -const formOpts = formOptions({ - defaultValues: { - firstName: '', - lastName: '', - employed: false, - jobTitle: '', - } as Employee, -}) -``` - -## Form Instance - -A Form Instance is an object that represents an individual form and provides methods and properties for working with the form. You create a form instance using the `TanStackFormController` interface provided by `@tanstack/lit-form`. The `TanStackFormController` is instantiated with the current form's (`this`) class and some default form options. It initializes the form state, handles form submission, and provides methods to manage form fields and their validation. - -```tsx -#form = new TanStackFormController(this, { - defaultValues: { - firstName: '', - lastName: '', - employed: false, - jobTitle: '', - } as Employee, -}) -``` - -You may also create a form instance without using `formOptions` by using the standalone `TanStackFormController` API: - -```tsx -#form = new TanStackFormController(this, { - ...formOpts, -}) -``` - -## Field - -A Field represents a single form input element, such as a text input or a checkbox. Fields are created using the `field(FieldOptions, callback)` provided by the form instance. The component accepts a `FieldOptions` object and a callback function that receives a `FieldApi` object. This object provides methods to get the current value of the field, handle input changes, and handle blur events. - -For Example: - -```ts - ${this.#form.field( - { - name: `firstName`, - validators: { - onChange: ({ value }) => - value.length < 3 ? "Not long enough" : undefined, - }, - }, - (field: FieldApi${this.#form.api.state.errorMap.onDynamic?.firstName}
` - } -} -``` - -## Usage with Other Validation Logic - -You can use `onDynamic` validation alongside other validation logic, such as `onChange` or `onBlur`. - -```ts -import { LitElement, html } from 'lit' -import { customElement } from 'lit/decorators.js' -import { TanStackFormController, revalidateLogic } from '@tanstack/lit-form' - -@customElement('my-form') -export class MyForm extends LitElement { - #form = new TanStackFormController(this, { - defaultValues: { - firstName: '', - lastName: '', - }, - validationLogic: revalidateLogic(), - validators: { - onChange: ({ value }) => { - if (!value.firstName) { - return { firstName: 'A first name is required' } - } - return undefined - }, - onDynamic: ({ value }) => { - if (!value.lastName) { - return { lastName: 'A last name is required' } - } - return undefined - }, - }, - }) - - render() { - return html` -${this.#form.api.state.errorMap.onChange?.firstName}
-${this.#form.api.state.errorMap.onDynamic?.lastName}
-${this.title}
- ${this.form.field( - { name: 'firstName' }, - (field) => html` -${error.message}
`)} + `, +) ``` -Synchronous and Asynchronous validations can coexist. For example, it is possible to define both `onBlur` and `onBlurAsync` on the same field: +## Asynchronous validation and debouncing -```ts -import { html, nothing } from 'lit' -;`${this.#form.field( - { - name: 'age', - validators: { - onBlur: ({ value }) => - value < 13 ? 'You must be at least 13' : undefined, - onBlurAsync: async ({ value }) => { - const currentAge = await fetchCurrentAgeOnProfile() - return value < currentAge ? 'You can only increase the age' : undefined - }, - }, - }, - (field) => { - return html` - - - ${!field.state.meta.isValid - ? html`${field.state.meta.errors.join(', ')}` - : nothing} - ` - }, -)}` -``` - -The synchronous validation method (`onBlur`) is run first and the asynchronous method (`onBlurAsync`) is only run if the synchronous one (`onBlur`) succeeds. To change this behaviour, set the `asyncAlways` option to `true`, and the async method will be run regardless of the result of the sync method. - -### Built-in Debouncing - -While async calls are the way to go when validating against the database, running a network request on every keystroke is a good way to DDOS your database. - -Instead, we enable an easy method for debouncing your `async` calls by adding a single property: +`run` may return a promise. Put cheap synchronous checks first and use +`bailIfInvalid` to avoid unnecessary requests: ```ts -;`${this.#form.field( +validators: [ { - name: 'age', - asyncDebounceMs: 500, - validators: { - onChangeAsync: async ({ value }) => { - // ... - }, - }, - }, - (field) => { - return html`` + triggers: ['change'], + run: ({ value }) => + value.length >= 3 ? undefined : 'Use at least 3 characters', }, -)}` -``` - -This will debounce every async call with a 500ms delay. You can even override this property on a per-validation property: - -```ts -;`${this.#form.field( { - name: 'age', - asyncDebounceMs: 500, - validators: { - onChangeAsyncDebounceMs: 1500, - onChangeAsync: async ({ value }) => { - // ... - }, - onBlurAsync: async ({ value }) => { - // ... - }, + triggers: ['change'], + triggerDebounceMs: 500, + bailIfInvalid: true, + run: async ({ value }) => { + const available = await checkUsername(value) + return available ? undefined : 'That username is already taken' }, }, - (field) => { - return html`` - }, -)}` +] ``` -This will run `onChangeAsync` every 1500ms while `onBlurAsync` will run every 500ms. - -## Validation through Schema Libraries - -While functions provide more flexibility and customization over your validation, they can be a bit verbose. To help solve this, there are libraries that provide schema-based validation to make shorthand and type-strict validation substantially easier. You can also define a single schema for your entire form and pass it to the form level, errors will be automatically propagated to the fields. +Submit validation always runs immediately, even when a trigger is debounced. +`field.meta.isValidating` and `form.api.state.isValidating` expose pending work. +Render form-wide pending state through `form.subscribe(...)` so it stays +reactive. -### Standard Schema Libraries +## Standard Schema validation -TanStack Form natively supports all libraries following the [Standard Schema specification](https://github.com/standard-schema/standard-schema), most notably: - -- [Zod](https://zod.dev/) -- [Valibot](https://valibot.dev/) -- [ArkType](https://arktype.io/) -- [Effect/Schema](https://effect.website/docs/schema/standard-schema/) - -_Note:_ make sure to use the latest version of the schema libraries as older versions might not support Standard Schema yet. - -> Validation will not provide you with transformed values. Use submission handling (docs pending). - -To use schemas from these libraries you can pass them to the `validators` props as you would do with a custom function: +Any Standard Schema implementation can be supplied as `run`: ```ts import { z } from 'zod' -import { LitElement, html } from 'lit' -import { customElement } from 'lit/decorators.js' -import { TanStackFormController } from '@tanstack/lit-form' -const userSchema = z.object({ - age: z.number().gte(13, 'You must be 13 to make an account'), +const accountSchema = z.object({ + email: z.string().email(), + age: z.number().min(13), }) -@customElement('my-form') -export class MyForm extends LitElement { - #form = new TanStackFormController(this, { - defaultValues: { - age: 0, +private form = new TanStackFormController(this, { + defaultValues: { email: '', age: 0 }, + validators: [ + { + triggers: ['change'], + run: accountSchema, }, - validators: { - onChange: userSchema, - }, - }) - - render() { - return html` -Please enter your first name
- ${this.#form.field( - { - name: `firstName`, - validators: { - onChange: ({ value }) => - value.length < 3 ? 'Not long enough' : undefined, + return html` + + ` } } + +customElements.define('profile-form', ProfileForm) ``` -Be aware that you need -to handle updating the element and form yourself as seen in the example above. +The important pieces are: + +- `defaultValues` define the complete initial value and drive type inference. +- `form.field(...)` subscribes only its Lit child part to one field. Its render + callback exposes `field.value`, `field.meta`, and event handlers. +- Validators are ordered objects with a `run` function and explicit + `triggers`. +- `form.subscribe(...)` updates only its child part when the selected form state + changes. +- The public form API is available through `form.api`; calling + `form.api.handleSubmit()` validates before running `onSubmit`. diff --git a/docs/framework/lit/reference/classes/TanStackFormController.md b/docs/framework/lit/reference/classes/TanStackFormController.md index 91e62aa15c..8e966931cf 100644 --- a/docs/framework/lit/reference/classes/TanStackFormController.md +++ b/docs/framework/lit/reference/classes/TanStackFormController.md @@ -3,73 +3,71 @@ id: TanStackFormController title: TanStackFormController --- -# Class: TanStackFormController\