fix(form): a server rejection that names fields now marks those fields (#2966)

The server's VALIDATION_FAILED always carried fields[] — one entry per offending field with a human message — and every form dropped it, showing one undirected toast. On a long form the offending field is usually off-screen, so Save appeared to do nothing.

Three layers, each of which was dropping the detail: @object-ui/react gains extractFieldErrors(err), normalising the three shapes the error arrives in (typed ValidationError, the raw client error whose details falls back to the whole response body, and the hand-rolled duck-typed shape); @object-ui/data-objectstack maps a 400 VALIDATION_FAILED onto the ValidationError class that had been exported and never once constructed, and `create` now normalises at all (only `update` did); the form renderer applies entries via form.setError — but only when every rejected field has a visible input, falling through to the banner otherwise so the part the user cannot see inline is still said out loud.

The toast + scroll-and-focus of the first offender is shared with the client-side invalid handler (announceFieldErrors): to the person filling in the form these are the same event — only the referee differs.

Removes the reason for client-side predicate mirroring (#2962): a form no longer has to guess what the server will reject. Non-field failures (403, permission denials) take exactly the path they took before.

14 + 6 new tests; 107 files / 1073 tests green; tsc clean on all three changed packages.

Author: os-zhuang

.changeset/server-field-errors-on-inputs.md

@@ -0,0 +1,58 @@
+---
+"@object-ui/react": minor
+"@object-ui/data-objectstack": minor
+"@object-ui/components": minor
+---
+
+fix(form): a server rejection that names fields now marks those fields (objectstack#3896)
+
+The server has always said which field it rejected. `@objectstack/objectql`'s
+validators throw `VALIDATION_FAILED` with `fields[]` — one entry per offending
+field, each with a human `message` — and both the REST layer and the runtime
+dispatcher serve that as a 400 with the entries intact.
+
+Every form dropped them. The submit handler caught the rejection, ran the
+message through `extractWriteErrorMessage`, and showed **one undirected toast**:
+the user was told something was wrong but not *what*, on a surface that already
+knows how to mark an input — and already does exactly that for client-side
+validation. On a long form the offending field was often off-screen, so "创建"
+appeared to do nothing.
+
+**Now the two failures behave identically, because they share one
+implementation.** The per-field marking, the toast naming the fields, and the
+scroll-and-focus of the first offender (#2793) were extracted from the
+client-side invalid handler; the server path calls the same function. As far as
+the person filling in the form is concerned these are the same event — only the
+referee differs.
+
+Three layers, each of which was dropping the detail:
+
+- **`@object-ui/react`** — new `extractFieldErrors(err)` (exported alongside
+  `extractWriteErrorMessage` / `isPermissionError`) normalises the three shapes
+  the error can arrive in: a typed `ValidationError` from the ObjectStack
+  adapter, the raw `@objectstack/client` error (whose `details` falls back to the
+  whole response body, which is where `fields[]` lands), and a hand-rolled error
+  carrying `fields` directly — the server duck-types that shape identically, so
+  the client must not be pickier than the server. Entries with no usable `field`
+  are **dropped rather than guessed at**: marking an innocent input is worse than
+  the generic toast.
+- **`@object-ui/data-objectstack`** — `normaliseClientError` now maps a 400
+  `VALIDATION_FAILED` onto the `ValidationError` class that has sat in
+  `errors.ts` since the package was written, exported and **never once
+  constructed**. Its `validationErrors: Array<{ field, message }>` shape was
+  already exactly right. `create` also now normalises at all: only `update` did,
+  so a rejected insert reached callers as the raw client error — and a create is
+  the path that most often trips required-field validation.
+- **`@object-ui/components`** — the form renderer maps the entries onto
+  `form.setError` and takes over the failure, **but only when every rejected
+  field has a visible input to carry it**. If the server also rejected something
+  the form does not render, it falls through to the banner, whose top-level
+  message concatenates every field's reason — so the part the user cannot see
+  inline is still said out loud instead of silently dropped.
+
+This also removes the need for the client-side predicate mirroring added in
+#2962: a form no longer has to guess what the server will reject in order to
+warn about it beforehand, and mirrored predicates drift.
+
+Non-field failures (403 / permission denials / anything without `fields[]`) take
+exactly the path they took before.

packages/components/src/renderers/form/__tests__/form-server-field-errors.test.tsx

@@ -0,0 +1,171 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * A server rejection that names fields must mark those fields.
+ *
+ * `@objectstack/objectql`'s validators throw `VALIDATION_FAILED` with
+ * `fields[]`, and both the REST layer and the runtime dispatcher serve it as a
+ * 400 with those entries intact. The form caught the rejection, showed one
+ * generic toast, and dropped `fields[]` — so a user told "Validation failed"
+ * had to guess WHICH input was wrong, on a surface that already knows how to
+ * mark it and already does exactly that for client-side validation.
+ *
+ * The sibling test `form-invalid-scroll.test.tsx` pins the client-side half;
+ * these two paths now share one implementation, so they must behave alike.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor, cleanup } from '@testing-library/react';
+import { ComponentRegistry } from '@object-ui/core';
+import { toast } from '../../../ui/sonner';
+
+beforeAll(async () => {
+  await import('../../../renderers');
+}, 30000);
+
+let toastErrorSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  toastErrorSpy = vi.spyOn(toast, 'error').mockImplementation(() => 'id' as any);
+  if (!(Element.prototype as any).scrollIntoView) {
+    (Element.prototype as any).scrollIntoView = () => {};
+  }
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+/** The wire shape the server sends, as `@objectstack/client` decorates it. */
+function validationFailure(fields: Array<{ field: string; code?: string; message?: string }>) {
+  const message = fields.map((f) => f.message ?? `${f.field} (${f.code})`).join('; ');
+  return Object.assign(new Error(message), {
+    code: 'VALIDATION_FAILED',
+    httpStatus: 400,
+    details: { error: message, code: 'VALIDATION_FAILED', fields, object: 'crm_opportunity' },
+  });
+}
+
+function renderForm(fields: any[], onSubmit: (data: any) => Promise<unknown>) {
+  const Form = ComponentRegistry.get('form')!;
+  return render(
+    <Form
+      schema={{
+        type: 'form',
+        mode: 'create',
+        showSubmit: true,
+        showCancel: false,
+        submitLabel: 'Create',
+        fields,
+        onSubmit,
+      }}
+    />,
+  );
+}
+
+const submit = () => fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+const FIELDS = [
+  { name: 'title', label: 'Title', type: 'input' },
+  { name: 'stage', label: 'Stage', type: 'input' },
+];
+
+describe('form renderer — server-rejected fields', () => {
+  it("writes the server's reason under the offending input", async () => {
+    const onSubmit = vi.fn().mockRejectedValue(
+      validationFailure([{ field: 'title', code: 'required', message: 'Title is required' }]),
+    );
+    renderForm(FIELDS, onSubmit);
+
+    submit();
+
+    await waitFor(() => expect(screen.getByText('Title is required')).toBeTruthy());
+  });
+
+  it('scrolls and focuses the first rejected field, as a client-side failure does', async () => {
+    const onSubmit = vi.fn().mockRejectedValue(
+      validationFailure([{ field: 'stage', code: 'invalid_option', message: 'Stage is not a valid option' }]),
+    );
+    const { container } = renderForm(FIELDS, onSubmit);
+    const stageWrap = container.querySelector('[data-field="stage"]') as HTMLElement;
+    const scrollSpy = vi.fn();
+    stageWrap.scrollIntoView = scrollSpy;
+
+    submit();
+
+    await waitFor(() => expect(scrollSpy).toHaveBeenCalled());
+    await waitFor(() => expect(stageWrap.contains(document.activeElement)).toBe(true));
+  });
+
+  it('names the rejected fields in the toast', async () => {
+    const onSubmit = vi.fn().mockRejectedValue(
+      validationFailure([{ field: 'title', message: 'Title is required' }]),
+    );
+    renderForm(FIELDS, onSubmit);
+
+    submit();
+
+    await waitFor(() => expect(toastErrorSpy).toHaveBeenCalled());
+    // The field LABEL, not its machine name.
+    expect(String(toastErrorSpy.mock.calls[0][0])).toMatch(/Title/);
+  });
+
+  it('marks every rejected field, not just the first', async () => {
+    const onSubmit = vi.fn().mockRejectedValue(
+      validationFailure([
+        { field: 'title', message: 'Title is required' },
+        { field: 'stage', message: 'Stage is not a valid option' },
+      ]),
+    );
+    renderForm(FIELDS, onSubmit);
+
+    submit();
+
+    await waitFor(() => expect(screen.getByText('Title is required')).toBeTruthy());
+    expect(screen.getByText('Stage is not a valid option')).toBeTruthy();
+  });
+
+  it('falls back to the generic banner when a rejected field has no input to carry it', async () => {
+    // A field the form does not render cannot be marked inline. Taking over the
+    // failure anyway would silently drop the part the user cannot see, so the
+    // top-level message — which names every field — is shown instead.
+    const onSubmit = vi.fn().mockRejectedValue(
+      validationFailure([
+        { field: 'title', message: 'Title is required' },
+        { field: 'owner_id', message: 'Owner is required' },
+      ]),
+    );
+    renderForm(FIELDS, onSubmit);
+
+    submit();
+
+    await waitFor(() => expect(toastErrorSpy).toHaveBeenCalled());
+    expect(String(toastErrorSpy.mock.calls[0][0])).toMatch(/Owner is required/);
+  });
+
+  it('leaves a non-field failure on the generic path', async () => {
+    const forbidden = Object.assign(new Error('insufficient privileges'), {
+      code: 'FORBIDDEN',
+      httpStatus: 403,
+      details: { error: 'insufficient privileges', code: 'FORBIDDEN' },
+    });
+    const onSubmit = vi.fn().mockRejectedValue(forbidden);
+    const { container } = renderForm(FIELDS, onSubmit);
+    const titleWrap = container.querySelector('[data-field="title"]') as HTMLElement;
+    const scrollSpy = vi.fn();
+    titleWrap.scrollIntoView = scrollSpy;
+
+    submit();
+
+    await waitFor(() => expect(toastErrorSpy).toHaveBeenCalled());
+    // Nothing is attributable to a field, so no input is marked or scrolled to.
+    expect(scrollSpy).not.toHaveBeenCalled();
+  });
+});

packages/components/src/renderers/form/form.tsx

@@ -29,7 +29,7 @@ import { AlertCircle, ChevronDown, ChevronRight, Loader2, Maximize2, Check, X }
 import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogFooter } from '../../ui/dialog';
 import { cn } from '../../lib/utils';
 import React from 'react';
-import { SchemaRendererContext, usePredicateScope, isPermissionError, extractWriteErrorMessage } from '@object-ui/react';
+import { SchemaRendererContext, usePredicateScope, isPermissionError, extractWriteErrorMessage, extractFieldErrors } from '@object-ui/react';
 import { createSafeTranslation } from '@object-ui/i18n';
 
 /** Inline section header rendered as a virtual field inside a flat SchemaRenderer field list.
@@ -502,6 +502,45 @@ ComponentRegistry.register('form',
       return () => subscription.unsubscribe();
     }, [form, onDirtyChangeProp]);
 
+    /**
+     * Tell the user WHICH fields are wrong, wherever the verdict came from.
+     *
+     * Toast naming the offending fields, then scroll the FIRST of them into
+     * view (in declared/visual order, not the caller's key order) and focus a
+     * control inside it — the field wrapper carries `data-field` (FormItem), so
+     * this reaches custom widgets that RHF's own focus cannot (#2793).
+     *
+     * Extracted from the client-side invalid handler so the SERVER-rejection
+     * path gets identical treatment. The two failures are the same event as far
+     * as the person filling the form is concerned; only the referee differs.
+     */
+    const announceFieldErrors = (names: string[]) => {
+      if (names.length === 0) return;
+      const labels = names.map((n) => fieldLabelByName[n] || n);
+      const MAX = 3;
+      const fieldsText = labels.slice(0, MAX).join('、') + (labels.length > MAX ? '…' : '');
+      toast.error(t('validation.formInvalid', { fields: fieldsText }));
+
+      const errored = new Set(names);
+      const firstName =
+        (fields as FormFieldConfig[])
+          .map((f) => f?.name)
+          .find((n): n is string => Boolean(n) && errored.has(n as string)) ?? names[0];
+      const root: ParentNode = formRef.current ?? document;
+      const escaped =
+        typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
+          ? CSS.escape(firstName)
+          : firstName.replace(/["\\]/g, '\\$&');
+      const target = root.querySelector<HTMLElement>(`[data-field="${escaped}"]`);
+      if (target) {
+        target.scrollIntoView?.({ behavior: 'smooth', block: 'center' });
+        const focusable = target.querySelector<HTMLElement>(
+          'input:not([type="hidden"]), select, textarea, button, [tabindex]:not([tabindex="-1"]), [contenteditable="true"]',
+        );
+        focusable?.focus?.({ preventScroll: true });
+      }
+    };
+
     // Handle form submission
     const handleSubmit = form.handleSubmit(async (data) => {
       setIsSubmitting(true);
@@ -555,6 +594,37 @@ ComponentRegistry.register('form',
           form.reset();
         }
       } catch (error) {
+        // The server can reject field-by-field: `@objectstack/objectql`'s
+        // validators throw `VALIDATION_FAILED` with `fields[]`, and both the
+        // REST layer and the runtime dispatcher serve it as a 400 with those
+        // entries intact. Every form used to drop them and show one undirected
+        // toast — telling the user something was wrong, but not WHAT, on a
+        // surface that already knows how to mark the input. Mark them.
+        const fieldErrors = extractFieldErrors(error);
+        if (fieldErrors) {
+          const known = fieldErrors.filter((fe) =>
+            (fields as FormFieldConfig[]).some((f) => f?.name === fe.field),
+          );
+          for (const fe of known) {
+            form.setError(fe.field, {
+              type: 'server',
+              // Fall back to the envelope's top-level text rather than leaving
+              // a marked field with no reason next to it.
+              message: fe.message || extractWriteErrorMessage(error) || t('form.submitFailed'),
+            });
+          }
+          // Only take over the whole failure when EVERY rejected field has a
+          // visible input to carry it. If the server also rejected something
+          // this form does not render, fall through: the top-level message
+          // concatenates every field's reason, so the part the user cannot see
+          // inline is still said out loud instead of silently dropped.
+          if (known.length > 0 && known.length === fieldErrors.length) {
+            announceFieldErrors(known.map((fe) => fe.field));
+            // A fully-attributed rejection is not a form-level failure — the
+            // banner would just repeat what is now written under each input.
+            return;
+          }
+        }
         // A rejected write used to be rendered verbatim, which put raw server
         // diagnostics in front of end users — untranslated, and leaking the
         // object's machine name and the record id, e.g.
@@ -587,36 +657,7 @@ ComponentRegistry.register('form',
       // is often scrolled out of view — the user clicks 创建 and sees nothing
       // happen. Surface a toast naming the fields so the feedback is visible
       // regardless of scroll position (mirrors the server-error toast above).
-      const names = Object.keys(validationErrors || {});
-      if (names.length === 0) return;
-      const labels = names.map((n) => fieldLabelByName[n] || n);
-      const MAX = 3;
-      const fieldsText = labels.slice(0, MAX).join('、') + (labels.length > MAX ? '…' : '');
-      toast.error(t('validation.formInvalid', { fields: fieldsText }));
-
-      // #2793: the toast alone still leaves the user hunting — in a long form
-      // the offending field is off-screen. Scroll the FIRST errored field into
-      // view (in declared/visual order, not RHF's error-key order) and focus a
-      // focusable control inside it. The field wrapper carries `data-field`
-      // (FormItem); works for custom widgets that RHF's own focus can't reach.
-      const errored = new Set(names);
-      const firstName =
-        (fields as FormFieldConfig[])
-          .map((f) => f?.name)
-          .find((n): n is string => Boolean(n) && errored.has(n as string)) ?? names[0];
-      const root: ParentNode = formRef.current ?? document;
-      const escaped =
-        typeof CSS !== 'undefined' && typeof CSS.escape === 'function'
-          ? CSS.escape(firstName)
-          : firstName.replace(/["\\]/g, '\\$&');
-      const target = root.querySelector<HTMLElement>(`[data-field="${escaped}"]`);
-      if (target) {
-        target.scrollIntoView?.({ behavior: 'smooth', block: 'center' });
-        const focusable = target.querySelector<HTMLElement>(
-          'input:not([type="hidden"]), select, textarea, button, [tabindex]:not([tabindex="-1"]), [contenteditable="true"]',
-        );
-        focusable?.focus?.({ preventScroll: true });
-      }
+      announceFieldErrors(Object.keys(validationErrors || {}));
     });
 
     // Handle cancel