feat(form): scroll to first invalid field on validation error

useForm scrolls the first [aria-invalid="true"] into view after a 422, matching the per-field scroll the app layer previously wired by hand. The primitive useValidationErrors stays DOM-free; scrolling lives in the opinionated useForm and is opt-out via {scrollToError: false}.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Confmc

docs/packages/form.md

@@ -71,6 +71,26 @@ const {errors, submitting, handleSubmit} = useForm<Field>(http, {keyMapper: came
 The two source territories diverged on exactly one axis: one camelCased the error keys, the other used them raw. `keyMapper` (default identity) is the single injection point that absorbs that divergence, so the package fits both without forking.
 :::
 
+## Scroll to the First Error
+
+On a 422, `useForm` scrolls the first invalid field into view so the user lands on the first thing to fix — it targets the first `[aria-invalid="true"]` element (the marker the presentation layer sets from the error bag) and calls `scrollIntoView({behavior: 'smooth', block: 'center'})` after the mark is painted. `useForm` derives no ids and marks no fields itself.
+
+```typescript
+useForm<Field>(http); // scrolls on error (default)
+useForm<Field>(http, {scrollToError: false}); // opt out
+```
+
+By default the query is **document-wide** — the first `[aria-invalid="true"]` in document order — which is right for a single form. When several forms share a page, pass each form's root as `scrollRoot` so a 422 in one never scrolls to another's field:
+
+```typescript
+const formEl = ref<HTMLElement | null>(null);
+useForm<Field>(http, {scrollRoot: formEl}); // scopes the scroll to formEl's subtree
+```
+
+`scrollRoot` keeps a form's scroll within its own subtree, but it does **not** isolate forms that share one `HttpService`: a 422 fills every such form's error bag (see [Scoping & Backend Contract](#scoping--backend-contract) below), so a co-mounted form still scrolls to its _own_ matching field on an unrelated submit. Give concurrently-mounted forms separate `HttpService` instances to avoid that.
+
+`useValidationErrors` never scrolls (the DOM-free primitive). A consumer that already scrolls on error should opt out with `scrollToError: false` to avoid a double scroll.
+
 ## Composing the Primitives
 
 `useForm` is `useValidationErrors` + `useFormSubmit` wired together. Reach for the primitives directly when you want one half without the other — e.g. a validation-less confirm action needs the submit guard but no 422 middleware:
@@ -106,10 +126,12 @@ const {handleSubmit, submitting} = useFormSubmit(validation);
 
 The one-call entry point. Returns everything from both primitives.
 
-| Parameter           | Type                      | Description                                          |
-| ------------------- | ------------------------- | ---------------------------------------------------- |
-| `httpService`       | `HttpService`             | The `fs-http` service whose 422 responses to observe |
-| `options.keyMapper` | `(key: string) => string` | Remaps raw backend field keys (default: identity)    |
+| Parameter               | Type                       | Description                                                                                                                               |
+| ----------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `httpService`           | `HttpService`              | The `fs-http` service whose 422 responses to observe                                                                                      |
+| `options.keyMapper`     | `(key: string) => string`  | Remaps raw backend field keys (default: identity)                                                                                         |
+| `options.scrollToError` | `boolean`                  | Scroll the first invalid field into view on a 422 (default: `true`; see [Scroll to the First Error](#scroll-to-the-first-error))          |
+| `options.scrollRoot`    | `Ref<HTMLElement \| null>` | Scope the `scrollToError` query to a form's subtree; omit for document-wide (see [Scroll to the First Error](#scroll-to-the-first-error)) |
 
 **Returns:**
 

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@script-development/fs-form",
-    "version": "0.1.1",
+    "version": "0.2.0",
     "description": "Reactive form-submit helpers: double-submit guard plus 422 validation-error binding for fs-http",
     "homepage": "https://packages.script.nl/packages/form",
     "license": "MIT",

packages/form/package.json

@@ -3,6 +3,7 @@ import type {HttpService} from '@script-development/fs-http';
 import type {UseForm, UseFormOptions} from './types';
 
 import {useFormSubmit} from './form-submit';
+import {useScrollToFirstError} from './scroll-to-first-error';
 import {useValidationErrors} from './validation-errors';
 
 /**
@@ -18,14 +19,20 @@ import {useValidationErrors} from './validation-errors';
  * validation-less confirm action).
  *
  * @param httpService the fs-http service whose 422 responses to observe.
- * @param options     `keyMapper` remaps raw backend field keys (default identity).
+ * @param options     `keyMapper` remaps raw backend field keys (default identity);
+ *                    `scrollToError` scrolls the first invalid field into view on a
+ *                    422 (default `true`); `scrollRoot` scopes that scroll to a
+ *                    form's own subtree.
  */
 export const useForm = <T extends string = string>(
     httpService: HttpService,
     options: UseFormOptions = {},
 ): UseForm<T> => {
+    const {scrollToError = true, scrollRoot} = options;
     const validation = useValidationErrors<T>(httpService, options);
     const {handleSubmit, submitting} = useFormSubmit(validation);
 
+    if (scrollToError) useScrollToFirstError(validation.errors, scrollRoot);
+
     return {errors: validation.errors, clearErrors: validation.clearErrors, handleSubmit, submitting};
 };

packages/form/src/form.ts

@@ -0,0 +1,33 @@
+import type {Ref} from 'vue';
+
+import {watch} from 'vue';
+
+import type {ValidationErrors} from './types';
+
+/**
+ * Scroll the first invalid field into view whenever `errors` changes. Keys off
+ * `[aria-invalid="true"]`, which the presentation layer sets from the error bag —
+ * fs-form derives no ids and marks no fields itself. A no-op when nothing is
+ * marked invalid: an empty bag (e.g. after `clearErrors`) leaves no marked field,
+ * so the query finds none.
+ *
+ * `root` scopes the query to a form's own subtree; omit it and the query is
+ * document-wide (first `[aria-invalid="true"]` in document order) — fine for a
+ * single form, but scope per form when several share a page. When `root` is given
+ * but its ref is `null` (the element is not mounted), nothing scrolls — it does
+ * not fall back to the document, so opted-in scoping is never silently re-widened.
+ *
+ * `flush: 'post'` runs the callback after the DOM update that paints
+ * `aria-invalid`, so the query sees the freshly-marked field. Call inside a
+ * component `setup()` (as `useForm` does) so the watcher stops on unmount.
+ */
+export const useScrollToFirstError = (errors: Ref<ValidationErrors>, root?: Ref<HTMLElement | null>): void => {
+    watch(
+        errors,
+        () => {
+            const scope = root === undefined ? document : root.value;
+            scope?.querySelector('[aria-invalid="true"]')?.scrollIntoView({behavior: 'smooth', block: 'center'});
+        },
+        {flush: 'post'},
+    );
+};

packages/form/src/scroll-to-first-error.ts

@@ -36,8 +36,27 @@ export type UseFormSubmit = {
     submitting: Ref<boolean>;
 };
 
-/** Options for `useForm` (currently the validation options). */
-export type UseFormOptions = UseValidationErrorsOptions;
+/** Options for `useForm`: the validation options plus `useForm`-only behaviour. */
+export type UseFormOptions = UseValidationErrorsOptions & {
+    /**
+     * After a 422 populates `errors`, scroll the first invalid field
+     * (`[aria-invalid="true"]`) into view. The presentation layer marks invalid
+     * controls with `aria-invalid`; `useForm` reads that attribute and derives no
+     * ids and marks no fields itself. Set `false` to opt out — or use
+     * `useValidationErrors` directly for a DOM-free error bag.
+     * @default true
+     */
+    scrollToError?: boolean;
+    /**
+     * Element ref that scopes the `scrollToError` query to one form's subtree.
+     * Omit it and the query is document-wide (the first `[aria-invalid="true"]` in
+     * document order) — fine for a single form, but pass the form's root ref when
+     * several forms share a page, so a 422 in one never scrolls to another's field.
+     * While the ref is `null` (element not mounted) nothing scrolls; passing a root
+     * never falls back to a document-wide search.
+     */
+    scrollRoot?: Ref<HTMLElement | null>;
+};
 
 /**
  * Everything `useForm` returns: the field-error bag and `clearErrors` from

packages/form/src/types.ts

@@ -3,8 +3,8 @@ import type {AxiosResponseError, HttpService, ResponseErrorMiddlewareFunc} from
 import type {AxiosError} from 'axios';
 
 import {mount} from '@vue/test-utils';
-import {afterEach, describe, expect, it, vi} from 'vitest';
-import {defineComponent} from 'vue';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {defineComponent, h, nextTick, ref} from 'vue';
 
 import type {UseForm, UseFormOptions} from '../src';
 
@@ -53,6 +53,47 @@ const mountForm = <T extends string = string>(httpService: HttpService, options?
     return {wrapper, result: () => result};
 };
 
+// Mounts (attached to the document) a form that renders one field marked `aria-invalid`
+// while the error bag is non-empty — the shape the scroll watcher queries for.
+const mountFieldForm = (httpService: HttpService, options?: UseFormOptions, markInvalid = true) => {
+    let result!: UseForm;
+    const wrapper = mount(
+        defineComponent({
+            setup() {
+                result = useForm(httpService, options);
+                return () =>
+                    h('input', {
+                        'aria-invalid': markInvalid && Object.keys(result.errors.value).length > 0 ? 'true' : 'false',
+                    });
+            },
+        }),
+        {attachTo: document.body},
+    );
+    return {wrapper, result: () => result};
+};
+
+// Mounts (attached) a form whose invalid field sits inside (or outside) a `scrollRoot` element,
+// to prove the query is scoped to that root's subtree.
+const mountScopedForm = (httpService: HttpService, fieldInsideRoot: boolean) => {
+    const scrollRoot = ref<HTMLElement | null>(null);
+    let result!: UseForm;
+    const wrapper = mount(
+        defineComponent({
+            setup() {
+                result = useForm(httpService, {scrollRoot});
+                const marked = () => (Object.keys(result.errors.value).length > 0 ? 'true' : 'false');
+                return () =>
+                    h('div', [
+                        h('div', {ref: scrollRoot}, [fieldInsideRoot ? h('input', {'aria-invalid': marked()}) : null]),
+                        fieldInsideRoot ? null : h('input', {'aria-invalid': marked()}),
+                    ]);
+            },
+        }),
+        {attachTo: document.body},
+    );
+    return {wrapper, result: () => result};
+};
+
 const deferred = () => {
     let resolve!: () => void;
     const promise = new Promise<void>((res) => {
@@ -150,3 +191,117 @@ describe('useForm', () => {
         expect(errorMiddlewares).toHaveLength(0);
     });
 });
+
+describe('useForm scroll-to-error', () => {
+    let scrollIntoView: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        scrollIntoView = vi.spyOn(Element.prototype, 'scrollIntoView').mockImplementation(() => {});
+    });
+
+    it('scrolls the first invalid field into view after a 422', async () => {
+        const {httpService, triggerError} = createMockHttpService();
+        const {wrapper} = mountFieldForm(httpService);
+
+        triggerError(422, {errors: {email: ['Taken']}});
+        await nextTick();
+
+        expect(scrollIntoView).toHaveBeenCalledWith({behavior: 'smooth', block: 'center'});
+        wrapper.unmount();
+    });
+
+    it('scrolls to the first invalid field in document order when several are marked', async () => {
+        const {httpService, triggerError} = createMockHttpService();
+        let result!: UseForm;
+        const wrapper = mount(
+            defineComponent({
+                setup() {
+                    result = useForm(httpService);
+                    const marked = () => (Object.keys(result.errors.value).length > 0 ? 'true' : 'false');
+                    return () =>
+                        h('div', [h('input', {'aria-invalid': marked()}), h('input', {'aria-invalid': marked()})]);
+                },
+            }),
+            {attachTo: document.body},
+        );
+
+        triggerError(422, {errors: {email: ['Taken']}});
+        await nextTick();
+
+        const invalid = document.querySelectorAll('[aria-invalid="true"]');
+        expect(invalid).toHaveLength(2);
+        expect(scrollIntoView).toHaveBeenCalledTimes(1);
+        expect(scrollIntoView.mock.contexts[0]).toBe(invalid[0]);
+        wrapper.unmount();
+    });
+
+    it('does not scroll when scrollToError is false', async () => {
+        const {httpService, triggerError} = createMockHttpService();
+        const {wrapper} = mountFieldForm(httpService, {scrollToError: false});
+
+        triggerError(422, {errors: {email: ['Taken']}});
+        await nextTick();
+
+        expect(scrollIntoView).not.toHaveBeenCalled();
+        wrapper.unmount();
+    });
+
+    it('does not scroll again once the error bag is cleared', async () => {
+        const {httpService, triggerError} = createMockHttpService();
+        const {wrapper, result} = mountFieldForm(httpService);
+
+        triggerError(422, {errors: {email: ['Taken']}});
+        await nextTick();
+        expect(scrollIntoView).toHaveBeenCalledTimes(1);
+
+        result().clearErrors();
+        await nextTick();
+        expect(scrollIntoView).toHaveBeenCalledTimes(1);
+        wrapper.unmount();
+    });
+
+    it('no-ops when a 422 marks no field invalid', async () => {
+        const {httpService, triggerError} = createMockHttpService();
+        const {wrapper} = mountFieldForm(httpService, undefined, false);
+
+        triggerError(422, {errors: {email: ['Taken']}});
+        await nextTick();
+
+        expect(scrollIntoView).not.toHaveBeenCalled();
+        wrapper.unmount();
+    });
+
+    it('scopes the scroll to scrollRoot when provided', async () => {
+        const {httpService, triggerError} = createMockHttpService();
+        const {wrapper} = mountScopedForm(httpService, true);
+
+        triggerError(422, {errors: {email: ['Taken']}});
+        await nextTick();
+
+        expect(scrollIntoView).toHaveBeenCalledWith({behavior: 'smooth', block: 'center'});
+        wrapper.unmount();
+    });
+
+    it('does not scroll to an invalid field outside scrollRoot', async () => {
+        const {httpService, triggerError} = createMockHttpService();
+        const {wrapper} = mountScopedForm(httpService, false);
+
+        triggerError(422, {errors: {email: ['Taken']}});
+        await nextTick();
+
+        expect(scrollIntoView).not.toHaveBeenCalled();
+        wrapper.unmount();
+    });
+
+    it('does not fall back to the document when scrollRoot is null', async () => {
+        const {httpService, triggerError} = createMockHttpService();
+        const scrollRoot = ref<HTMLElement | null>(null); // passed but never bound -> stays null
+        const {wrapper} = mountFieldForm(httpService, {scrollRoot});
+
+        triggerError(422, {errors: {email: ['Taken']}});
+        await nextTick();
+
+        expect(scrollIntoView).not.toHaveBeenCalled();
+        wrapper.unmount();
+    });
+});