feat(uat-batch-20): form-error UX primitive — scroll-to-first-error hook + summary banner

Two new building blocks for the platform-wide form-error UX rework.
Expense form adopts both as the validation that the pattern works
before the broader sweep across the ~29 useForm callers.

- `useFormScrollToError(handleSubmit, errors)` — wraps RHF's
  handleSubmit. On validation failure it locates the first errored
  field via `[name="..."]` (or id fallback), walks ancestors to find
  the nearest scrolling container (key for forms inside Sheet /
  Dialog bodies that own their own overflow-y), and
  scrollTo({ behavior: 'smooth' }) + focus({ preventScroll }) on it.
  Type-loose handleSubmit signature so 2-arg and 3-arg useForm()
  callers (input vs transformed types) both work.
- `<FormErrorSummary errors={errors} labels={…}>` — top-of-form alert
  banner listing each failed field as a clickable anchor. Renders
  only when ≥2 errors (single-error case is handled by the hook
  alone). role="alert" aria-live="polite" for SR users.
- expense-form-dialog adopts both: `onSubmitWithScroll(onSubmit)`
  replaces the bare `handleSubmit(onSubmit)`, plus a labelled
  `<FormErrorSummary>` at the top of the form. Closes the loop on
  the silent-no-op zod-refine bug fixed in PR1 (the underlying
  setValue() fix already routes errors through formState; this
  surfaces them visibly).

tsc clean. 1419/1419 vitest pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/expenses/expense-form-dialog.tsx

@@ -11,6 +11,8 @@ import { Checkbox } from '@/components/ui/checkbox';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { Textarea } from '@/components/ui/textarea';
+import { FormErrorSummary } from '@/components/forms/form-error-summary';
+import { useFormScrollToError } from '@/hooks/use-form-scroll-to-error';
 import {
   Select,
   SelectContent,
@@ -75,6 +77,11 @@ export function ExpenseFormDialog({ open, onOpenChange, expense }: ExpenseFormDi
       paymentStatus: 'unpaid',
     },
   });
+  // Scroll-to-first-error wrapper around handleSubmit. On validation
+  // failure it auto-scrolls + focuses the first errored input so reps
+  // can see what failed without hunting (especially important on tall
+  // drawer-based forms like this one).
+  const onSubmitWithScroll = useFormScrollToError(handleSubmit, errors);
 
   useEffect(() => {
     if (open && expense) {
@@ -208,7 +215,19 @@ export function ExpenseFormDialog({ open, onOpenChange, expense }: ExpenseFormDi
           <SheetTitle>{isEdit ? 'Edit Expense' : 'New Expense'}</SheetTitle>
         </SheetHeader>
 
-        <form onSubmit={handleSubmit(onSubmit)} className="space-y-4 mt-4">
+        <form onSubmit={onSubmitWithScroll(onSubmit)} className="space-y-4 mt-4">
+          <FormErrorSummary
+            errors={errors}
+            labels={{
+              expenseDate: 'Date',
+              amount: 'Amount',
+              currency: 'Currency',
+              category: 'Category',
+              paymentMethod: 'Payment method',
+              receiptFileIds: 'Receipt',
+              noReceiptAcknowledged: 'Receipt',
+            }}
+          />
           <div className="space-y-2">
             <Label htmlFor="expenseDate">Date *</Label>
             <Input

src/components/forms/form-error-summary.tsx

@@ -0,0 +1,78 @@
+'use client';
+
+import { AlertCircle } from 'lucide-react';
+import type { FieldErrors, FieldValues } from 'react-hook-form';
+
+import { cn } from '@/lib/utils';
+
+interface FormErrorSummaryProps<TFieldValues extends FieldValues> {
+  errors: FieldErrors<TFieldValues>;
+  /**
+   * Optional override map for human-readable field labels. Falls back
+   * to the schema-supplied message label or the raw field name.
+   */
+  labels?: Partial<Record<keyof TFieldValues & string, string>>;
+  className?: string;
+}
+
+/**
+ * Top-of-form validation summary. Renders only when ≥2 fields have
+ * errors; a single-error form is handled by the
+ * `useFormScrollToError` hook (no banner needed). Each entry is an
+ * anchor link that scrolls + focuses the offending input on click.
+ */
+export function FormErrorSummary<TFieldValues extends FieldValues>({
+  errors,
+  labels,
+  className,
+}: FormErrorSummaryProps<TFieldValues>) {
+  const entries = Object.entries(errors).filter(([, err]) => err != null);
+  if (entries.length < 2) return null;
+
+  function onJump(name: string) {
+    const node =
+      (document.querySelector(`[name="${name}"]`) as HTMLElement | null) ??
+      (document.getElementById(name) as HTMLElement | null);
+    if (!node) return;
+    node.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    if (typeof node.focus === 'function') {
+      window.setTimeout(() => node.focus({ preventScroll: true }), 50);
+    }
+  }
+
+  return (
+    <div
+      role="alert"
+      aria-live="polite"
+      className={cn(
+        'rounded-md border border-destructive/40 bg-destructive/5 px-3 py-2',
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2 text-sm font-medium text-destructive">
+        <AlertCircle className="size-4" aria-hidden />
+        Please fix the following before submitting:
+      </div>
+      <ul className="mt-1.5 ml-6 list-disc text-xs text-destructive/90">
+        {entries.map(([name, err]) => {
+          const label =
+            (labels as Record<string, string> | undefined)?.[name] ??
+            (err && typeof err === 'object' && 'message' in err && typeof err.message === 'string'
+              ? err.message
+              : name);
+          return (
+            <li key={name}>
+              <button
+                type="button"
+                onClick={() => onJump(name)}
+                className="hover:underline focus:outline-none focus:underline"
+              >
+                {label}
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

src/hooks/use-form-scroll-to-error.ts

@@ -0,0 +1,90 @@
+'use client';
+
+import { useCallback } from 'react';
+import type { FieldErrors, FieldValues } from 'react-hook-form';
+
+// react-hook-form's handleSubmit is generic across the input vs.
+// transformed types. We don't need the strictness here — the wrapper
+// just passes its handler through to whatever handleSubmit the caller
+// gave us. Use a loose type so 2-arg and 3-arg useForm() both work.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyHandleSubmit = (
+  onValid: any,
+  onInvalid?: any,
+) => (e?: React.BaseSyntheticEvent) => Promise<void>;
+
+/**
+ * Find the nearest scrolling ancestor of a node — accounts for the
+ * common case of forms rendered inside a Sheet / Dialog body that owns
+ * its own overflow-y. Falls back to `window` when no ancestor scrolls.
+ */
+function findScrollContainer(el: HTMLElement | null): HTMLElement | null {
+  let cur: HTMLElement | null = el?.parentElement ?? null;
+  while (cur) {
+    const style = window.getComputedStyle(cur);
+    const overflowY = style.overflowY;
+    if ((overflowY === 'auto' || overflowY === 'scroll') && cur.scrollHeight > cur.clientHeight) {
+      return cur;
+    }
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Wrap react-hook-form's `handleSubmit` so validation failures scroll
+ * the first errored field into view and focus it. Critical on tall
+ * drawers / dialogs where the failing field is below the fold —
+ * without this the user is dropped at the top of the form with no
+ * indication of what failed.
+ *
+ * Usage:
+ * ```
+ * const { handleSubmit, formState: { errors }, ... } = useForm(...);
+ * const onSubmit = useFormScrollToError(handleSubmit, errors);
+ * <form onSubmit={onSubmit(myHandler)}>...</form>
+ * ```
+ *
+ * `errors` is taken from `formState` so the hook reads the FIRST key
+ * (insertion order matches field render order in practice).
+ */
+export function useFormScrollToError<TFieldValues extends FieldValues>(
+  handleSubmit: AnyHandleSubmit,
+  errors: FieldErrors<TFieldValues>,
+) {
+  return useCallback(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (onValid: (data: any) => void | Promise<void>) => {
+      return handleSubmit(onValid, () => {
+        // react-hook-form calls this on validation failure. We already
+        // have `errors` from formState — read the first key and scroll
+        // its DOM node into view.
+        const firstName = Object.keys(errors)[0];
+        if (!firstName) return;
+        // Find by `name` first (most input components forward `name`
+        // from `register`), then by `id` (fallback for custom Inputs).
+        const node =
+          (document.querySelector(`[name="${firstName}"]`) as HTMLElement | null) ??
+          (document.getElementById(firstName) as HTMLElement | null);
+        if (!node) return;
+        const container = findScrollContainer(node);
+        if (container) {
+          // Manually compute position so we scroll inside the
+          // container, not the page.
+          const cRect = container.getBoundingClientRect();
+          const nRect = node.getBoundingClientRect();
+          const offset = nRect.top - cRect.top + container.scrollTop - cRect.height / 2;
+          container.scrollTo({ top: offset, behavior: 'smooth' });
+        } else {
+          node.scrollIntoView({ block: 'center', behavior: 'smooth' });
+        }
+        if (typeof node.focus === 'function') {
+          // Defer focus until after the smooth scroll has started so
+          // the focus ring is visible.
+          window.setTimeout(() => node.focus({ preventScroll: true }), 50);
+        }
+      });
+    },
+    [handleSubmit, errors],
+  );
+}