From 55d69a2698955bdb481509fb71fdd57cf2aa60fb Mon Sep 17 00:00:00 2001 From: 0froq Date: Sat, 21 Nov 2026 09:37:23 +0800 Subject: [PATCH 1/3] feat: accept nested validation error paths in useForm errors Validators report nested messages as dotted keys such as `profile.name` or `contacts.0.email`. The error map, `setError()` and `clearErrors()` now take those keys, so apps no longer need a cast to read or clear them. --- .../react/test/unit/use-form.typecheck.ts | 21 +++++++++++++++++++ .../solid/test/unit/form-errors.typecheck.ts | 21 +++++++++++++++++++ .../svelte/test/unit/form-errors.typecheck.ts | 21 +++++++++++++++++++ packages/void/src/pages/client.ts | 2 ++ packages/void/src/pages/form-presentation.ts | 21 ++++++++++++++++--- .../vue/test/unit/form-errors.typecheck.ts | 21 +++++++++++++++++++ 6 files changed, 104 insertions(+), 3 deletions(-) diff --git a/packages/react/test/unit/use-form.typecheck.ts b/packages/react/test/unit/use-form.typecheck.ts index cad0ce449..08b274d9b 100644 --- a/packages/react/test/unit/use-form.typecheck.ts +++ b/packages/react/test/unit/use-form.typecheck.ts @@ -5,9 +5,30 @@ declare module 'void/routes' { interface PageActionMap { '/__form-options/notes': { actions: { create: { body: { title: string } } } }; '/__form-options/notes/:id': { body: { title: string }; params: { id: string } }; + '/__form-options/nested': { + body: { profile: { name: string }; contacts: Array<{ email: string }> }; + }; } } +export function checkNestedErrorPaths(): void { + const form = useForm('/__form-options/nested', { + profile: { name: '' }, + contacts: [{ email: '' }], + }); + const name: string | undefined = form.errors['profile.name']; + const email: string | undefined = form.errors['contacts.0.email']; + void name; + void email; + form.setError('profile.name', 'Required name'); + form.setError('contacts.0.email', 'Required email'); + form.clearErrors('profile', 'contacts', 'contacts.0.email'); + // @ts-expect-error Nested error paths must name a field in the action body. + form.setError('profile.missing', 'Invalid'); + // @ts-expect-error Array segments must be numeric array indices. + form.clearErrors('contacts.first'); +} + export function checkFormOptions(): void { useForm( '/__form-options/notes?create', diff --git a/packages/solid/test/unit/form-errors.typecheck.ts b/packages/solid/test/unit/form-errors.typecheck.ts index 5849df88e..b302da404 100644 --- a/packages/solid/test/unit/form-errors.typecheck.ts +++ b/packages/solid/test/unit/form-errors.typecheck.ts @@ -4,9 +4,30 @@ import { useForm } from '../../src/runtime/use-form.ts'; declare module 'void/routes' { interface PageActionMap { '/__form-errors/solid': { body: { email: string } }; + '/__form-errors/solid-nested': { + body: { profile: { name: string }; contacts: Array<{ email: string }> }; + }; } } +export function checkNestedErrorPaths(): void { + const form = useForm('/__form-errors/solid-nested', { + profile: { name: '' }, + contacts: [{ email: '' }], + }); + const name: string | undefined = form.errors['profile.name']; + const email: string | undefined = form.errors['contacts.0.email']; + void name; + void email; + form.setData('contacts', [{ email: 'alex@example.com' }]); + form.setError('profile.name', 'Required name'); + form.clearErrors('profile', 'contacts', 'contacts.0.email'); + // @ts-expect-error Nested error paths must name a field in the action body. + form.setError('profile.missing', 'Invalid'); + // @ts-expect-error Array segments must be numeric array indices. + form.clearErrors('contacts.first'); +} + export function checkFieldErrors(): void { const form = useForm('/__form-errors/solid', { email: '' }); form.setError('email', 'Invalid email'); diff --git a/packages/svelte/test/unit/form-errors.typecheck.ts b/packages/svelte/test/unit/form-errors.typecheck.ts index 024ba82b0..be7220ce2 100644 --- a/packages/svelte/test/unit/form-errors.typecheck.ts +++ b/packages/svelte/test/unit/form-errors.typecheck.ts @@ -4,9 +4,30 @@ import { useForm } from '../../src/runtime/use-form.svelte.ts'; declare module 'void/routes' { interface PageActionMap { '/__form-errors/svelte': { body: { email: string } }; + '/__form-errors/svelte-nested': { + body: { profile: { name: string }; contacts: Array<{ email: string }> }; + }; } } +export function checkNestedErrorPaths(): void { + const form = useForm('/__form-errors/svelte-nested', { + profile: { name: '' }, + contacts: [{ email: '' }], + }); + const name: string | undefined = form.errors['profile.name']; + const email: string | undefined = form.errors['contacts.0.email']; + void name; + void email; + form.errors['contacts.0.email'] = 'Required email'; + form.setError('profile.name', 'Required name'); + form.clearErrors('profile', 'contacts', 'contacts.0.email'); + // @ts-expect-error Nested error paths must name a field in the action body. + form.setError('profile.missing', 'Invalid'); + // @ts-expect-error Array segments must be numeric array indices. + form.clearErrors('contacts.first'); +} + export function checkFieldErrors(): void { const form = useForm('/__form-errors/svelte', { email: '' }); form.setError('email', 'Invalid email'); diff --git a/packages/void/src/pages/client.ts b/packages/void/src/pages/client.ts index f2039b7a3..a14a84d81 100644 --- a/packages/void/src/pages/client.ts +++ b/packages/void/src/pages/client.ts @@ -649,6 +649,8 @@ export { formRetryMessage, formSubmissionBlocked, scheduleFormRetry, + type FormErrorPath, + type FormErrors, type FormModel, type FormMethod, type FormState, diff --git a/packages/void/src/pages/form-presentation.ts b/packages/void/src/pages/form-presentation.ts index f5d0772da..81e1356f2 100644 --- a/packages/void/src/pages/form-presentation.ts +++ b/packages/void/src/pages/form-presentation.ts @@ -20,8 +20,23 @@ export type FormStatus = { readonly wasSuccessful: boolean; readonly recentlySuccessful: boolean; }; +/** + * A body field plus the dotted nested paths a validator reports for it, such as `profile.name` + * or `contacts.0.email`. The recursion is capped so a recursive body type stays cheap to check. + */ +export type FormErrorPath = []> = Depth['length'] extends 6 + ? never + : T extends ReadonlyArray + ? `${number}` | `${number}.${FormErrorPath}` + : T extends object + ? { + [K in keyof T & string]: T[K] extends (...args: Array) => unknown + ? never + : K | `${K}.${FormErrorPath}`; + }[keyof T & string] + : never; /** Field-keyed validation messages; a field without an error is absent. */ -export type FormErrors = Partial>; +export type FormErrors = Partial, string>>; /** * How an adapter's apps change `data` and `errors`, following its framework's idiom. * `'in-place'`: apps edit them directly (Vue, Svelte). @@ -40,8 +55,8 @@ export type FormState = FormStatus & Readonly<{ reset(options: FormResetOptions, ...fields: ReadonlyArray): void; reset(...fields: ReadonlyArray): void; - setError(field: keyof TData & string, message: string): void; - clearErrors(...fields: ReadonlyArray): void; + setError(field: FormErrorPath, message: string): void; + clearErrors(...fields: ReadonlyArray>): void; clearError(): void; }>; /** diff --git a/packages/vue/test/unit/form-errors.typecheck.ts b/packages/vue/test/unit/form-errors.typecheck.ts index ab336a67f..35c64b660 100644 --- a/packages/vue/test/unit/form-errors.typecheck.ts +++ b/packages/vue/test/unit/form-errors.typecheck.ts @@ -4,9 +4,30 @@ import { useForm } from '../../src/runtime/use-form.ts'; declare module 'void/routes' { interface PageActionMap { '/__form-errors/vue': { body: { email: string } }; + '/__form-errors/vue-nested': { + body: { profile: { name: string }; contacts: Array<{ email: string }> }; + }; } } +export function checkNestedErrorPaths(): void { + const form = useForm('/__form-errors/vue-nested', { + profile: { name: '' }, + contacts: [{ email: '' }], + }); + const name: string | undefined = form.errors['profile.name']; + const email: string | undefined = form.errors['contacts.0.email']; + void name; + void email; + form.errors['contacts.0.email'] = 'Required email'; + form.setError('profile.name', 'Required name'); + form.clearErrors('profile', 'contacts', 'contacts.0.email'); + // @ts-expect-error Nested error paths must name a field in the action body. + form.setError('profile.missing', 'Invalid'); + // @ts-expect-error Array segments must be numeric array indices. + form.clearErrors('contacts.first'); +} + export function checkFieldErrors(): void { const form = useForm('/__form-errors/vue', { email: '' }); form.setError('email', 'Invalid email'); From 2817e8dd50f5a3fa0118a149f824fc03b7da4c00 Mon Sep 17 00:00:00 2001 From: 0froq Date: Sat, 21 Nov 2026 09:37:51 +0800 Subject: [PATCH 2/3] fix: clear nested form errors with their parent field Editing or replacing a parent object or array now clears the errors of the fields below it, matching how editing a scalar clears that field's error. Clearing a parent with `clearErrors()` does the same and keeps unrelated errors. Svelte snapshots the parent field when a handler reports a nested error, because the parent is what changed in `data`. --- packages/react/src/runtime/use-form.ts | 11 ++-- packages/react/test/unit/use-form.test.ts | 59 +++++++++++++++++++ packages/solid/src/runtime/use-form.ts | 11 +--- packages/solid/test/unit/form-errors.test.ts | 45 ++++++++++++-- .../svelte/src/runtime/use-form.svelte.ts | 17 +++++- packages/svelte/test/unit/use-form.test.ts | 27 +++++++++ packages/void/src/pages/client.ts | 2 + packages/void/src/pages/form-presentation.ts | 17 ++++++ packages/vue/src/runtime/use-form.ts | 13 +++- packages/vue/test/unit/use-form.test.ts | 32 ++++++++++ 10 files changed, 207 insertions(+), 27 deletions(-) diff --git a/packages/react/src/runtime/use-form.ts b/packages/react/src/runtime/use-form.ts index fdf55b190..f9f3ad80a 100644 --- a/packages/react/src/runtime/use-form.ts +++ b/packages/react/src/runtime/use-form.ts @@ -15,6 +15,7 @@ import { isAbortError, isCallSiteActionError, isEqualFormValue, + omitFormErrors, parseFormResetArgs, submitAction, type FormResetOptions, @@ -200,11 +201,10 @@ export function useForm( const target = callbackOutcomeRef.current ?? outcome; setErrorEdits((prev) => { const current = resolveOutcomeErrors(target, prev); - if (!(field in current)) { + const next = omitFormErrors(current, [field]); + if (next === current) { return prev; } - const next = { ...current }; - delete next[field]; return { ...(prev?.source === target ? prev : { source: target }), errors: next, @@ -241,10 +241,7 @@ export function useForm( if (fields.length === 0) { return { ...base, errors: EMPTY_ERRORS }; } - const next = { ...resolveOutcomeErrors(target, prev) }; - for (const field of fields) { - delete next[field]; - } + const next = omitFormErrors(resolveOutcomeErrors(target, prev), fields); return { ...base, errors: next }; }); }, diff --git a/packages/react/test/unit/use-form.test.ts b/packages/react/test/unit/use-form.test.ts index 8bca58a20..d95561a12 100644 --- a/packages/react/test/unit/use-form.test.ts +++ b/packages/react/test/unit/use-form.test.ts @@ -22,6 +22,9 @@ import { useIslandForm, type IslandFormReturn } from '../../src/runtime/use-isla declare module 'void/routes' { interface PageActionMap { '/__form-callbacks/notes': { actions: { create: { body: { title: string } } } }; + '/__form-nested/contacts': { + body: { profile: { name: string }; contacts: Array<{ email: string }> }; + }; } } @@ -247,6 +250,62 @@ describe('useForm callbacks', () => { expect(formRef.current!.error).toBe(actionError); }); + it('clears nested errors below a replaced parent field and a cleared parent', async () => { + type NestedForm = ReturnType>; + const formRef: { current: NestedForm | null } = { current: null }; + function App() { + formRef.current = useForm('/__form-nested/contacts', { + profile: { name: '' }, + contacts: [{ email: '' }], + }); + return null; + } + const router = routerWithVisit( + vi.fn(async () => ({ + errors: { + 'profile.name': 'Required name', + 'contacts.0.email': 'Required email', + title: 'Unrelated', + }, + })), + ); + await mountApp(createElement(RouterContext.Provider, { value: router }, createElement(App))); + const form = () => formRef.current!; + const submit = () => + act(async () => { + startTransition(() => { + form().post(new FormData()); + }); + }); + + await submit(); + expect(form().errors['profile.name']).toBe('Required name'); + expect(form().errors['contacts.0.email']).toBe('Required email'); + + await act(async () => { + form().setData('profile', { name: 'Alex' }); + }); + expect(form().errors['profile.name']).toBeUndefined(); + expect(form().errors['contacts.0.email']).toBe('Required email'); + + await act(async () => { + form().setData('contacts', [{ email: 'alex@example.com' }]); + }); + expect(form().errors).toEqual({ title: 'Unrelated' }); + + await submit(); + await act(async () => { + form().clearErrors('profile'); + }); + expect(form().errors['profile.name']).toBeUndefined(); + expect(form().errors['contacts.0.email']).toBe('Required email'); + + await act(async () => { + form().clearErrors('contacts'); + }); + expect(form().errors).toEqual({ title: 'Unrelated' }); + }); + it('fires onSuccess on each successful submit', async () => { const onSuccess = vi.fn(); const { formRef } = await mountForm( diff --git a/packages/solid/src/runtime/use-form.ts b/packages/solid/src/runtime/use-form.ts index 3f8cb3aff..7aa900c2b 100644 --- a/packages/solid/src/runtime/use-form.ts +++ b/packages/solid/src/runtime/use-form.ts @@ -8,6 +8,7 @@ import { isAbortError, isCallSiteActionError, isEqualFormValue, + omitFormErrors, parseFormResetArgs, submitAction, type FormResetOptions, @@ -105,15 +106,7 @@ export function useForm( } function clearErrors(...fields: ReadonlyArray) { - if (fields.length === 0) { - replaceErrors({}); - } else { - const next = { ...errors() }; - for (const field of fields) { - delete next[field]; - } - replaceErrors(next); - } + replaceErrors(fields.length === 0 ? {} : omitFormErrors(errors(), fields)); } function setFieldError(field: string, message: string) { diff --git a/packages/solid/test/unit/form-errors.test.ts b/packages/solid/test/unit/form-errors.test.ts index e6098acd4..954353029 100644 --- a/packages/solid/test/unit/form-errors.test.ts +++ b/packages/solid/test/unit/form-errors.test.ts @@ -20,17 +20,17 @@ const useForm = typedUseForm as unknown as ( defaults: Record, ) => TestForm; -function createForm() { - const [serverErrors, setServerErrors] = createSignal({ - email: 'Invalid email', - name: 'Required', - }); +function createForm( + server: Record = { email: 'Invalid email', name: 'Required' }, + defaults: Record = { email: '', name: '' }, +) { + const [serverErrors, setServerErrors] = createSignal(server); let form!: TestForm; const dispose = createRoot((dispose) => { createComponent(ErrorsContext.Provider, { value: serverErrors, get children() { - form = useForm('/test', { email: '', name: '' }); + form = useForm('/test', defaults); return null; }, }); @@ -66,6 +66,39 @@ describe('useForm router errors', () => { } }); + it('clears nested errors below a replaced parent field and a cleared parent', () => { + const { form, dispose } = createForm( + { + 'profile.name': 'Required name', + 'contacts.0.email': 'Required email', + name: 'Unrelated', + }, + { profile: { name: '' }, contacts: [{ email: '' }] }, + ); + try { + expect(form.errors).toEqual({ + 'profile.name': 'Required name', + 'contacts.0.email': 'Required email', + name: 'Unrelated', + }); + + form.clearErrors('profile'); + expect(form.errors).toEqual({ 'contacts.0.email': 'Required email', name: 'Unrelated' }); + + form.setError('profile.name', 'Required name'); + form.setData('profile', { name: 'Alex' }); + expect(form.errors).toEqual({ 'contacts.0.email': 'Required email', name: 'Unrelated' }); + + form.setData('contacts', [{ email: 'alex@example.com' }]); + expect(form.errors).toEqual({ name: 'Unrelated' }); + + form.clearErrors('name'); + expect(form.errors).toEqual({}); + } finally { + dispose(); + } + }); + it('shows new server results after earlier errors were cleared', () => { const { form, setServerErrors, dispose } = createForm(); try { diff --git a/packages/svelte/src/runtime/use-form.svelte.ts b/packages/svelte/src/runtime/use-form.svelte.ts index f01e7533d..6a76aeb9a 100644 --- a/packages/svelte/src/runtime/use-form.svelte.ts +++ b/packages/svelte/src/runtime/use-form.svelte.ts @@ -7,6 +7,7 @@ import { isAbortError, isCallSiteActionError, isEqualFormValue, + isFormErrorWithin, parseFormResetArgs, submitAction, type FormResetOptions, @@ -57,7 +58,11 @@ export function useForm( untrack(() => { for (const key of new Set([...Object.keys(dataSnapshot), ...Object.keys(current)])) { if (!isEqualFormValue(current[key], dataSnapshot[key])) { - delete errors[key]; + for (const errorKey of Object.keys(errors)) { + if (isFormErrorWithin(errorKey, key)) { + delete errors[errorKey]; + } + } } } dataSnapshot = current; @@ -65,9 +70,11 @@ export function useForm( }); // An input handler may validate its new value before the change effect runs. + // Nested error keys snapshot the parent field, which owns the changed value. function snapshotField(field: string) { + const [parent] = field.split('.'); untrack(() => { - dataSnapshot = { ...dataSnapshot, [field]: cloneFormValue(data[field]) }; + dataSnapshot = { ...dataSnapshot, [parent]: cloneFormValue(data[parent]) }; }); } @@ -106,7 +113,11 @@ export function useForm( errors = {}; } else { for (const field of fields) { - delete errors[field]; + for (const key of Object.keys(errors)) { + if (isFormErrorWithin(key, field)) { + delete errors[key]; + } + } } } } diff --git a/packages/svelte/test/unit/use-form.test.ts b/packages/svelte/test/unit/use-form.test.ts index 714c6d1be..1fa0593b7 100644 --- a/packages/svelte/test/unit/use-form.test.ts +++ b/packages/svelte/test/unit/use-form.test.ts @@ -18,6 +18,7 @@ type TestForm = { readonly pending: boolean; readonly wasSuccessful: boolean; setError(field: string, message: string): void; + clearErrors(...fields: Array): void; reset(): void; post(): Promise; }; @@ -154,6 +155,32 @@ describe('useForm field errors', () => { expect({ ...form.errors }).toEqual({ name: 'Name invalid' }); }); + it('clears nested errors below an edited parent field and a cleared parent', () => { + const form = mountForm({ profile: { name: '' }, contacts: [{ email: '' }] }); + form.setError('profile.name', 'Required name'); + form.setError('contacts.0.email', 'Required email'); + form.setError('name', 'Unrelated'); + svelte.flushSync(); + + form.data.profile = { name: 'Alex' }; + svelte.flushSync(); + expect({ ...form.errors }).toEqual({ 'contacts.0.email': 'Required email', name: 'Unrelated' }); + + form.data.contacts = [{ email: 'alex@example.com' }]; + svelte.flushSync(); + expect({ ...form.errors }).toEqual({ name: 'Unrelated' }); + + form.setError('profile.name', 'Required name'); + form.setError('contacts.0.email', 'Required email'); + form.clearErrors('profile'); + svelte.flushSync(); + expect({ ...form.errors }).toEqual({ 'contacts.0.email': 'Required email', name: 'Unrelated' }); + + form.clearErrors('contacts'); + svelte.flushSync(); + expect({ ...form.errors }).toEqual({ name: 'Unrelated' }); + }); + it('clears an error written before the field edit in the same handler', () => { const form = mountForm({ email: '' }); diff --git a/packages/void/src/pages/client.ts b/packages/void/src/pages/client.ts index a14a84d81..47a7d72b2 100644 --- a/packages/void/src/pages/client.ts +++ b/packages/void/src/pages/client.ts @@ -648,6 +648,8 @@ export { formErrorMessage, formRetryMessage, formSubmissionBlocked, + isFormErrorWithin, + omitFormErrors, scheduleFormRetry, type FormErrorPath, type FormErrors, diff --git a/packages/void/src/pages/form-presentation.ts b/packages/void/src/pages/form-presentation.ts index 81e1356f2..75348957d 100644 --- a/packages/void/src/pages/form-presentation.ts +++ b/packages/void/src/pages/form-presentation.ts @@ -76,6 +76,23 @@ export type IslandFormState = FormStatus & delete(url: RouteUrl): Promise; }>; +/** Whether an error key names `field` or a nested field below it, such as `profile.name`. */ +export function isFormErrorWithin(key: string, field: string): boolean { + return key === field || key.startsWith(`${field}.`); +} +/** + * Removes the errors of `fields` and of the nested fields below them, keeping unrelated errors. + * Returns the same object when no error matched, so callers can skip an update. + */ +export function omitFormErrors( + errors: Record, + fields: ReadonlyArray, +): Record { + const kept = Object.entries(errors).filter( + ([key]) => !fields.some((field) => isFormErrorWithin(key, field)), + ); + return kept.length === Object.keys(errors).length ? errors : Object.fromEntries(kept); +} export function formErrorMessage(form: Pick): string | null { return form.error?.message ?? (Object.values(form.errors).filter(Boolean).join('. ') || null); } diff --git a/packages/vue/src/runtime/use-form.ts b/packages/vue/src/runtime/use-form.ts index de1ebfe24..3608caf02 100644 --- a/packages/vue/src/runtime/use-form.ts +++ b/packages/vue/src/runtime/use-form.ts @@ -6,6 +6,7 @@ import { isAbortError, isCallSiteActionError, isEqualFormValue, + isFormErrorWithin, parseFormResetArgs, submitAction, type FormResetOptions, @@ -54,7 +55,7 @@ export function useForm( (val) => { for (const key of new Set([...Object.keys(dataSnapshot), ...Object.keys(val)])) { if (!isEqualFormValue(val[key], dataSnapshot[key])) { - delete errors[key]; + clearNestedErrors(key); } } dataSnapshot = val; @@ -79,6 +80,14 @@ export function useForm( dataSnapshot = cloneFormValue(data); } + function clearNestedErrors(field: string) { + for (const key of Object.keys(errors)) { + if (isFormErrorWithin(key, field)) { + delete errors[key]; + } + } + } + function clearErrors(...fields: ReadonlyArray) { if (fields.length === 0) { for (const key of Object.keys(errors)) { @@ -86,7 +95,7 @@ export function useForm( } } else { for (const field of fields) { - delete errors[field]; + clearNestedErrors(field); } } } diff --git a/packages/vue/test/unit/use-form.test.ts b/packages/vue/test/unit/use-form.test.ts index 01dbfaef4..27a067bd4 100644 --- a/packages/vue/test/unit/use-form.test.ts +++ b/packages/vue/test/unit/use-form.test.ts @@ -7,6 +7,7 @@ import { useIslandForm } from '../../src/runtime/use-island-form.ts'; type TestForm = { setError(field: string, message: string): void; + clearErrors(...fields: Array): void; readonly errors: Record; data: Record; hasChanges: boolean; @@ -162,6 +163,37 @@ describe('useForm setError', () => { await renderToString(app); }); + it('clears nested errors below a replaced parent field and a cleared parent', async () => { + const router = { + visit: async () => ({}), + } as unknown as VoidRouter; + const app = createSSRApp( + defineComponent({ + setup() { + const form = useForm('/test', { profile: { name: '' }, contacts: [{ email: '' }] }, {}); + form.setError('profile.name', 'Required name'); + form.setError('contacts.0.email', 'Required email'); + form.setError('name', 'Unrelated'); + form.data.profile = { name: 'Alex' }; + expect(form.errors['profile.name']).toBeUndefined(); + expect(form.errors['contacts.0.email']).toBe('Required email'); + form.data.contacts = [{ email: 'alex@example.com' }]; + expect(form.errors).toEqual({ name: 'Unrelated' }); + form.setError('profile.name', 'Required name'); + form.setError('contacts.0.email', 'Required email'); + form.clearErrors('profile'); + expect(form.errors['profile.name']).toBeUndefined(); + expect(form.errors['contacts.0.email']).toBe('Required email'); + form.clearErrors('contacts'); + expect(form.errors).toEqual({ name: 'Unrelated' }); + return () => h('form'); + }, + }), + ); + app.provide('__void_router', router); + await renderToString(app); + }); + it('keeps errors on other fields when one field changes', async () => { const router = { visit: async () => ({}), From 8f80909bf4522271ad4e899bdd95b3730aba4b3b Mon Sep 17 00:00:00 2001 From: 0froq Date: Sat, 21 Nov 2026 09:37:54 +0800 Subject: [PATCH 3/3] docs: describe nested validation error paths in useForm --- docs/guide/pages-routing/actions-and-forms.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/guide/pages-routing/actions-and-forms.md b/docs/guide/pages-routing/actions-and-forms.md index ff46fa30a..8ab50591a 100644 --- a/docs/guide/pages-routing/actions-and-forms.md +++ b/docs/guide/pages-routing/actions-and-forms.md @@ -153,7 +153,7 @@ The types are inferred from your action's `withValidator()` schema in the compan | Property / Method | Purpose | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` / `setData` | Current form values, typed to match the action's body schema. | -| `errors` | Field-level validation errors, keys typed to body field names. | +| `errors` | Field-level validation errors, keyed by body field and by nested paths such as `profile.name` or `contacts.0.email`. | | `error` | Action error, or `null`. | | `throwOnError` (option) | Set to `false` to keep authentication and server failures in `form.error` instead of throwing them. | | `post`, `put`, `patch`, `delete` | Submit the form with that method. In React these are native form action callbacks. | @@ -163,11 +163,11 @@ The types are inferred from your action's `withValidator()` schema in the compan | `recentlySuccessful` | `true` for 2 seconds after a successful submission. Useful for flash messages. | | `reset(...fields)` | Reset form data to the current defaults (last submitted values after success). Field names autocomplete. Pass `{ initial: true }` first to reset to the values passed to `useForm`. | | `resetOnSuccess` (option) | When `true`, a successful submit resets defaults to the mount-time values, and form data too unless it was edited during the submit. Useful for create forms that should clear after save. | -| `setError(field, message)` | Set a client-side validation error on a field. | -| `clearErrors(...fields)` | Clear validation errors. Field names autocomplete. | +| `setError(field, message)` | Set a client-side validation error on a field, including a nested path such as `profile.name`. | +| `clearErrors(...fields)` | Clear validation errors. Field names autocomplete. Clearing a parent field also clears the errors of its nested fields. | | `clearError()` | Clear `error`. | -Use `setError()` for client-side validation. Editing a field clears its error automatically. +Use `setError()` for client-side validation. Editing a field clears its error, including the errors of the fields nested below it. For a native React form, use `form.post`, `form.put`, `form.patch`, or `form.delete` as a native form action. For an awaitable mutation, use `action()`. In Vue, Svelte, and Solid, form submissions return `Promise`; catch thrown errors or use your framework's error handling.