feat(console): settings validation errors render against the fields that caused them (objectstack#4224 follow-up) (#3083)

A `SETTINGS_VALIDATION` rejection names the offending keys, and the settings page
threw all of it away — every failure collapsed into one toast carrying the
server's summary sentence, with nothing marked on the inputs.

That was not the console's fault. The server sent `fields` as a
`Record<key, message>` hung BESIDE `error.code`, a position `ApiErrorSchema`
never declared; it survived only because that schema is a plain `z.object` that
strips undeclared keys instead of rejecting them. `extractFieldErrors` reads
arrays (`details.fields` / `fields` / `validationErrors`), so a map at an
undeclared position matched nothing and returned null. objectstack#4224 moved it
to `error.details.fields` as the declared `FieldError[]` — which is what makes
this wiring a few lines rather than a parser.

- `SettingsField` gains an `error` prop, rendered in the slot the help text
  occupies rather than stacked under it.
- The mark is on the CONTROL, not just beside it — `aria-invalid` plus
  `aria-describedby` pointing at a `role="alert"` message, wired in `wrapper` so
  every input type is covered at once. Colour is not a cue for everyone.
- Cleared per-field the moment that field is edited, and wholesale on Discard,
  on reload, and on a successful save.
- Fields the server did not name stay unmarked; a failure carrying no field
  array behaves exactly as before. The toast still fires alongside the marks.

Five tests drive the real post-#4224 wire body rather than a hand-tuned fixture,
and were verified to fail without the wiring.

Author: os-zhuang

.changeset/settings-per-field-validation-errors.md

@@ -0,0 +1,35 @@
+---
+"@object-ui/console": patch
+---
+
+feat(settings): a rejected save marks the fields that caused it — objectstack#4224 follow-up
+
+A `SETTINGS_VALIDATION` rejection names the offending keys, and the settings page
+threw all of it away. Every failure collapsed into one toast carrying the
+server's summary sentence, with nothing marked on the inputs — so on a namespace
+with a dozen keys the user was told a value was wrong and left to find which.
+
+**That was not the console's fault, which is the part worth recording.** The
+server sent `fields` as a `Record<key, message>` hung *beside* `error.code`, a
+position `ApiErrorSchema` never declared — it survived only because the schema
+is a plain `z.object` and strips undeclared keys rather than rejecting them.
+`extractFieldErrors` reads arrays (`details.fields`, `fields`,
+`validationErrors`), so a map at an undeclared position matched nothing and
+returned `null`. objectstack#4224 moved it to `error.details.fields` as the
+declared `FieldError[]`, which is what makes this wiring a few lines rather than
+a parser.
+
+What changes for a user: the server's message now renders against the input that
+caused it, in the slot the help text occupies, and clears the moment that field
+is edited, on Discard, or on the next successful save. `SettingsField` gained an
+`error` prop; it sets `aria-invalid` and `aria-describedby` on the control and
+gives the message `role="alert"`, so the rejection is announced rather than being
+conveyed by colour alone.
+
+The toast still fires alongside the per-field marks. The offending field can be
+scrolled out of view or hidden behind a `visible` expression, and a save that
+appears to do nothing is the worse failure.
+
+Fields the server did not name are left unmarked — a wrong mark on an innocent
+input is worse than the generic toast that was already there — and a failure
+carrying no field array (a 500, an unknown namespace) behaves exactly as before.

apps/console/src/pages/settings/SettingsField.tsx

@@ -6,7 +6,7 @@
  * (which carries provenance and lock state).
  */
 
-import { useId } from 'react';
+import { cloneElement, isValidElement, useId, type ReactElement } from 'react';
 import {
   Input,
   Textarea,
@@ -46,6 +46,16 @@ export interface SettingsFieldProps {
   locked?: boolean;
   /** i18n helpers bound to the parent settings namespace. */
   labels?: SettingsLabelHelpers;
+  /**
+   * Server-side rejection for THIS field, from the last failed save
+   * (objectstack#4224). Already localized by the server — rendered verbatim,
+   * not re-worded here.
+   *
+   * Replaces the help text while present, rather than stacking below it: the
+   * two occupy the same slot and say the same kind of thing, and a description
+   * sitting under a red error reads as if the field has two states at once.
+   */
+  error?: string;
 }
 
 function InheritanceBadges({
@@ -132,8 +142,25 @@ function FieldDescription({ description }: { description?: string }) {
   return <p className="text-xs text-muted-foreground mt-1">{description}</p>;
 }
 
+/**
+ * The server's rejection for this field, in the slot the help text normally
+ * occupies (objectstack#4224).
+ *
+ * `role="alert"` so a screen reader announces it when it appears after a save
+ * attempt — the sighted cue is colour, which is not a cue at all for everyone.
+ * The `id` is what the input points `aria-describedby` at, so the association
+ * survives for assistive tech rather than being purely visual adjacency.
+ */
+function FieldError({ id, message }: { id: string; message: string }) {
+  return (
+    <p id={id} role="alert" className="text-xs text-destructive mt-1">
+      {message}
+    </p>
+  );
+}
+
 export function SettingsField(props: SettingsFieldProps) {
-  const { spec, resolved, value, onChange, onAction, locked, saving, labels } = props;
+  const { spec, resolved, value, onChange, onAction, locked, saving, labels, error } = props;
   const id = useId();
   const disabled = Boolean(locked || saving);
   const literalLabel = resolveLabel(spec.label);
@@ -231,11 +258,26 @@ export function SettingsField(props: SettingsFieldProps) {
 
   // -------- Inputs --------
 
+  // Wired onto the control itself, not just rendered beside it: `aria-invalid`
+  // is what announces "this one was rejected", and `aria-describedby` is what
+  // ties the message to the input for a screen reader. Every input type goes
+  // through `wrapper`, so marking it here covers all of them at once instead of
+  // per-case (objectstack#4224).
+  const errorId = `${id}-error`;
   const wrapper = (children: React.ReactNode) => (
     <div className="space-y-1.5 py-2">
       <FieldHeader spec={spec} resolved={resolved} labelText={fieldLabel} labels={labels} />
-      {children}
-      <FieldDescription description={fieldHelp} />
+      {error && isValidElement(children)
+        ? cloneElement(children as ReactElement<Record<string, unknown>>, {
+            'aria-invalid': true,
+            'aria-describedby': errorId,
+          })
+        : children}
+      {error ? (
+        <FieldError id={errorId} message={error} />
+      ) : (
+        <FieldDescription description={fieldHelp} />
+      )}
     </div>
   );
 

apps/console/src/pages/settings/SettingsView.tsx

@@ -11,6 +11,7 @@ import { useParams, useNavigate } from 'react-router-dom';
 import { toast } from 'sonner';
 import { Loader2, ArrowLeft, RotateCcw } from 'lucide-react';
 import { Button, Card, CardContent, Skeleton, Badge } from '@object-ui/components';
+import { extractFieldErrors } from '@object-ui/react';
 import { getIcon } from '../../utils/getIcon';
 import { SettingsField } from './SettingsField';
 import {
@@ -42,6 +43,12 @@ function evalVisibility(expr: string | undefined, data: Record<string, unknown>)
   }
 }
 
+/** `{ ...rest }` without `key`, returned as a new object so React sees the change. */
+function omitKey<T>(map: Record<string, T>, key: string): Record<string, T> {
+  const { [key]: _dropped, ...rest } = map;
+  return rest;
+}
+
 export function SettingsView() {
   const params = useParams<{ namespace?: string }>();
   const navigate = useNavigate();
@@ -53,6 +60,16 @@ export function SettingsView() {
   const [error, setError] = useState<string | null>(null);
   /** Live edit map keyed by spec.key. Falls back to resolved value when undefined. */
   const [draft, setDraft] = useState<Record<string, unknown>>({});
+  /**
+   * Per-field rejections from the last failed save, keyed by field name
+   * (objectstack#4224). Empty until a save comes back `SETTINGS_VALIDATION`.
+   *
+   * Before #4224 the server sent this as a `Record<key, message>` hung beside
+   * `error.code`, which `extractFieldErrors` could not read — so the whole
+   * batch collapsed into one toast that named no field. It now arrives as the
+   * declared `FieldError[]` under `error.details.fields`.
+   */
+  const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({});
 
   const load = useCallback(async () => {
     setLoading(true);
@@ -61,6 +78,7 @@ export function SettingsView() {
       const p = await getSettingsNamespace(namespace);
       setPayload(p);
       setDraft({});
+      setFieldErrors({});
     } catch (err: any) {
       setError(err?.message ?? 'Failed to load settings');
     } finally {
@@ -127,6 +145,7 @@ export function SettingsView() {
       const res = await saveSettingsNamespace(namespace, draft);
       setPayload({ ...payload, values: { ...values, ...res.values } });
       setDraft({});
+      setFieldErrors({});
       toast.success('Settings saved');
     } catch (err: any) {
       const apiError = err?.payload?.error;
@@ -135,6 +154,19 @@ export function SettingsView() {
         const key = lockedKeyOf(apiError);
         toast.error(key ? `Locked by environment: ${key}` : 'Locked by environment');
       } else {
+        // Per-field rejections render against the inputs that caused them
+        // (objectstack#4224). `extractFieldErrors` reads `details.fields`, so it
+        // is handed `error` — the object that carries `details` — not the
+        // whole body.
+        //
+        // The toast still fires: the offending field can be scrolled out of
+        // view, or hidden behind a `visible` expression, and a save that
+        // silently does nothing is the worse failure. It carries the server's
+        // summary message, which already names the fields.
+        const perField = extractFieldErrors(apiError);
+        if (perField?.length) {
+          setFieldErrors(Object.fromEntries(perField.map((f) => [f.field, f.message])));
+        }
         toast.error(err?.message ?? 'Save failed');
       }
     } finally {
@@ -194,11 +226,20 @@ export function SettingsView() {
                 spec={spec}
                 resolved={resolved}
                 value={current}
-                onChange={(v) => key && setDraft((d) => ({ ...d, [key]: v }))}
+                onChange={(v) => {
+                  if (!key) return;
+                  setDraft((d) => ({ ...d, [key]: v }));
+                  // Clear this field's rejection the moment it is edited. The
+                  // error describes the value the server saw, so keeping it on
+                  // screen while the user types contradicts what is in the box —
+                  // and the next save re-derives the set from scratch anyway.
+                  setFieldErrors((e) => (key in e ? omitKey(e, key) : e));
+                }}
                 onAction={spec.type === 'action_button' ? () => onAction(spec.id ?? key ?? 'test') : undefined}
                 locked={resolved?.locked}
                 saving={saving}
                 labels={labels}
+                error={key ? fieldErrors[key] : undefined}
               />
             );
           })}
@@ -211,7 +252,17 @@ export function SettingsView() {
               {dirtyKeys.length} unsaved change{dirtyKeys.length > 1 ? 's' : ''}
             </div>
             <div className="flex gap-2">
-              <Button variant="ghost" size="sm" onClick={() => setDraft({})} disabled={saving}>
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => {
+                  setDraft({});
+                  // Discarding reverts to the stored values, so rejections of
+                  // the edits being thrown away go with them.
+                  setFieldErrors({});
+                }}
+                disabled={saving}
+              >
                 <RotateCcw className="h-4 w-4 mr-1" /> Discard
               </Button>
               <Button onClick={onSave} disabled={saving}>