Skip to content

fix: support nested validation error paths in useForm - #890

Open
0froq wants to merge 3 commits into
voidzero-dev:mainfrom
0froq:fix/form-nested-error-paths
Open

0froq wants to merge 3 commits into
voidzero-dev:mainfrom
0froq:fix/form-nested-error-paths

Conversation

@0froq

@0froq 0froq commented Nov 21, 2026

Copy link
Copy Markdown
Collaborator

This description was drafted by an agent from the diff and the commands it ran. froQ🐸 has reviewed it.

Fixes #875

Description

useForm() now accepts and clears the dotted error keys that nested validators return.

The error map, setError() and clearErrors() are typed by a FormErrorPath union that walks the action body, so profile.name and contacts.0.email are valid keys while a field that does not exist is still a type error.

Replacing a parent object or array clears the errors of the fields below it, and clearErrors('profile') does the same, in all four adapters. Editing a scalar cleared only that exact error, so messages for nested values stayed after the value was fixed.

Svelte snapshots the parent field when a handler reports a nested error, because the parent is what changes in data.

Test

  • packages/react/test/unit/use-form.test.ts: clears nested errors below a replaced parent field and a cleared parent
  • packages/vue/test/unit/use-form.test.ts: same case name, under useForm setError
  • packages/svelte/test/unit/use-form.test.ts: clears nested errors below an edited parent field and a cleared parent
  • packages/solid/test/unit/form-errors.test.ts: clears nested errors below a replaced parent field and a cleared parent

Each one sets profile.name and contacts.0.email, replaces the parent, and asserts that only the unrelated error is left. All four fail on main, React and Vue with expected 'Required name' to be undefined, and the other two on the error map still holding three entries.

  • checkNestedErrorPaths() in packages/react/test/unit/use-form.typecheck.ts
  • checkNestedErrorPaths() in packages/{vue,svelte,solid}/test/unit/form-errors.typecheck.ts

They pin the nested keys as readable and clearable, and keep profile.missing and contacts.first rejected. On main, tsc -p packages/react reports TS7053 on form.errors['profile.name'].

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.
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`.
@0froq

0froq commented Nov 21, 2026

Copy link
Copy Markdown
Collaborator Author

👁️‍🗨️ Review this pull request with grouped, summarized diffs at:
👉 https://pulls.review/gh/voidzero-dev/void/890?from=0froq

raw result

💭 analyzed by openai-compatible/opencode-go/deepseek-v4.1-flash
🕰️ 2026-11-21 02:34 UTC
🔗 head 8f80909
🤖 automated by pulls.review

{
  "headSha": "8f80909bf4522271ad4e899bdd95b3730aba4b3b",
  "result": {
    "overallSummary": "`useForm()` only understood **top-level** body field names: a nested validator message like `profile.name` was neither typed (TS7053 when read) nor cleared when the parent value was replaced or `clearErrors('profile')` was called, so stale messages survived a fix. This PR makes error keys a `FormErrorPath` union derived from the action body, adds shared `isFormErrorWithin`/`omitFormErrors` helpers, and uses them in all four adapters so a replaced or cleared parent also drops the errors of its nested fields.",
    "groups": [
      {
        "key": "error-path-types",
        "label": "Nested error path types & helpers",
        "summary": "Foundation of the fix: `FormErrorPath` walks the action body as a dotted template-literal union (including numeric array segments) and replaces `keyof TData` in `FormErrors`, `setError()` and `clearErrors()`. Two pure helpers, `isFormErrorWithin` and `omitFormErrors`, encode \"this key belongs to that field\" so every adapter clears parents and children the same way.",
        "category": "core",
        "filePaths": [
          "packages/void/src/pages/form-presentation.ts",
          "packages/void/src/pages/client.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/void/src/pages/form-presentation.ts",
            "text": "Public type change: existing consumers that index `errors` with a plain `string` may now see stricter typing, since the record keys are a union rather than `keyof TData & string`."
          }
        ],
        "lineNotes": [
          {
            "path": "packages/void/src/pages/form-presentation.ts",
            "side": "additions",
            "line": 27,
            "text": "Recursion stops by resolving to `never` at depth 6, so a body nested deeper than that silently loses its nested error keys instead of producing an expensive or infinite type."
          },
          {
            "path": "packages/void/src/pages/form-presentation.ts",
            "side": "additions",
            "line": 30,
            "text": "Array segments are typed as `` `${number}` ``, so `contacts.0.email` is accepted but so is an out-of-range `contacts.99.email` — indices are not checked against the tuple length."
          },
          {
            "path": "packages/void/src/pages/form-presentation.ts",
            "side": "additions",
            "line": 94,
            "text": "Returning the *same* object when nothing matched is load-bearing: React's `setErrorEdits` compares by reference to skip a state update."
          }
        ]
      },
      {
        "key": "adapter-clearing",
        "label": "Adapters clear nested errors",
        "summary": "Wires the shared helpers into each framework adapter so editing a scalar or replacing a parent value drops every error key below it, and `clearErrors(field)` also clears nested keys. React and Solid delegate to `omitFormErrors`; Vue and Svelte mutate the existing error map in place, as their `'in-place'` editing idiom requires.",
        "category": "core",
        "filePaths": [
          "packages/react/src/runtime/use-form.ts",
          "packages/vue/src/runtime/use-form.ts",
          "packages/svelte/src/runtime/use-form.svelte.ts",
          "packages/solid/src/runtime/use-form.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/svelte/src/runtime/use-form.svelte.ts",
            "text": "Input handlers report a nested error before the change effect runs, so `snapshotField()` now snapshots the *parent* field (`field.split('.')[0]`) — the value that actually changes in `data` — otherwise the parent change is re-detected and the freshly set nested error is cleared again."
          }
        ],
        "lineNotes": [
          {
            "path": "packages/react/src/runtime/use-form.ts",
            "side": "additions",
            "line": 205,
            "text": "The early-return condition changed from `!(field in current)` to a reference check on `omitFormErrors`: previously `clearErrors`/edit of `profile` returned early when only `profile.name` existed, which is exactly the bug being fixed."
          }
        ]
      },
      {
        "key": "tests",
        "label": "Regression & type tests",
        "summary": "One runtime case per adapter sets `profile.name` and `contacts.0.email`, replaces/clears the parents, and asserts only the unrelated error remains; four `checkNestedErrorPaths()` typecheck functions pin the nested keys as readable and clearable while `profile.missing` and `contacts.first` stay rejected inside `@ts-expect-error`.",
        "category": "tests",
        "filePaths": [
          "packages/react/test/unit/use-form.test.ts",
          "packages/react/test/unit/use-form.typecheck.ts",
          "packages/vue/test/unit/use-form.test.ts",
          "packages/vue/test/unit/form-errors.typecheck.ts",
          "packages/svelte/test/unit/use-form.test.ts",
          "packages/svelte/test/unit/form-errors.typecheck.ts",
          "packages/solid/test/unit/form-errors.test.ts",
          "packages/solid/test/unit/form-errors.typecheck.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/solid/test/unit/form-errors.test.ts",
            "text": "`createForm()` gained `server`/`defaults` parameters with backwards-compatible defaults so the new case can seed nested server errors without a second fixture."
          },
          {
            "path": "packages/svelte/test/unit/use-form.test.ts",
            "text": "Cases call `svelte.flushSync()` between edits because the error clearing runs in an effect, not synchronously in the setter."
          }
        ]
      },
      {
        "key": "docs",
        "label": "Docs for nested error paths",
        "summary": "Updates the API table and the `setError()` guidance to say error keys can be dotted nested paths and that editing or clearing a parent field also clears the errors of its nested fields.",
        "category": "docs",
        "filePaths": [
          "docs/guide/pages-routing/actions-and-forms.md"
        ]
      }
    ],
    "schemaVersion": 1,
    "source": "llm",
    "generatedAt": "2026-11-21T02:34:06.868Z",
    "model": "openai-compatible/opencode-go/deepseek-v4.1-flash",
    "locale": "en"
  }
}

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

React useForm: nested validation error paths are rejected by types and survive parent updates

1 participant