fix(fields,components): deliver the validation slot to field widgets as error (#3222) (#3289)

`@objectstack/spec/ui`'s `FieldWidgetPropsSchema` declares `error?: string`;
`@object-ui/fields` declared `errorMessage?: string`. That looked like a naming
split, but the slot was dead under BOTH spellings: nothing in packages/ or
apps/ ever produced it, so the seven widgets computing
`aria-invalid={!!errorMessage}` computed it from a permanent `undefined`.
`aria-invalid` had never once been set on a failing field — and because a
widget writes its own attribute AFTER the props spread, those seven actively
OVERWROTE the correct `aria-invalid` that `<FormControl>`'s Radix Slot hands
down.

Two halves, both required:

- the form renderer now passes `fieldState.error?.message` down as `error`
  when it renders a registered widget (the producer that never existed);
- the slot adopts the spec's name across `FieldWidgetComponentProps` and the
  7 widgets, with no alias kept. #3221 had already closed the type, so the
  compiler — not grep — validated the rename.

Responsibilities stay split: the widget consumes `error` only to drive
`aria-invalid` on the control it renders; the message text remains with
`<FormMessage/>`. `required` is deliberately NOT lowered into widget props —
the required marker has exactly one author (`<FormLabel>`), and the a11y state
a widget could carry is `aria-required`, which needs no contract change.

Builtin field types strip `error` instead: they render inside `<FormControl>`,
whose Slot already supplies `aria-invalid`, so the prop would only reach the
DOM as a stray attribute.

Docs synced (plugin-development guide + skill, component.prompt.md — which also
used the spec's non-generic alias as a generic and destructured a `mode` prop
that exists on neither type).


Claude-Session: https://claude.ai/code/session_01NVPjPzmmAJ2Ngtvgg5MSRa

Co-authored-by: Claude <noreply@anthropic.com>

Author: xuyushun441-sys

.changeset/field-widget-error-slot-follows-spec.md

@@ -0,0 +1,86 @@
+---
+"@object-ui/fields": minor
+"@object-ui/components": minor
+---
+
+Field widgets are finally told when their field fails validation, and the props
+slot that carries it takes the name the published contract gives it
+(objectui#3222).
+
+**Breaking** for anyone implementing a field widget (see migration below). The
+repo version policy keeps this a `minor` — objectui's major tracks
+`@objectstack`'s — so read the bump as "breaking within objectui".
+
+## The a11y defect this fixes
+
+`@objectstack/spec/ui`'s `FieldWidgetPropsSchema` — the published contract that
+third-party and AI-authored field widgets are written against — has always
+declared `error?: string`. `@object-ui/fields` declared its own slot as
+`errorMessage`. That looked like a naming split; it was worse:
+
+```
+producers of `errorMessage` anywhere in packages/ + apps/ :  0
+reads of `errorMessage` in packages/fields/src            : 15  (7 widgets)
+reads of `props.error`                                    :  0
+```
+
+The slot was dead under BOTH spellings. No host ever passed it: the form
+renderer showed validation text through its own `<FormMessage/>` and never
+forwarded the prop. So `EmailField`, `CurrencyField`, `UrlField`,
+`RichTextField`, `PercentField`, `TextAreaField` and `PhoneField` each computed
+`aria-invalid={!!errorMessage}` from a value that was `undefined` forever —
+**`aria-invalid` had never once been set, and a screen reader was never told
+the field had failed validation.**
+
+Worse than "never set": `<FormControl>` is a Radix `Slot` that hands its child a
+CORRECT `aria-invalid`, but a widget's own attribute is written after the props
+spread, so it wins. Those seven widgets were actively overwriting the right
+answer with `false`.
+
+FROM: `renderFieldComponent` received no validation state, and the widget props
+type declared `errorMessage?: string`, which nothing produced.
+TO: the form renderer passes react-hook-form's `fieldState.error?.message` down
+as `error` when it renders a registered widget, and the props type declares
+`error?: string`. Both ends of the contract are live for the first time; a
+rename alone would only have swapped one dead key for another.
+
+## Migration for widget authors
+
+```diff
+-export function MyField({ value, onChange, field, readonly, errorMessage }: FieldWidgetComponentProps< string >) {
+-  return <Input value={value} aria-invalid={!!errorMessage} />;
++export function MyField({ value, onChange, field, readonly, error }: FieldWidgetComponentProps< string >) {
++  return <Input value={value} aria-invalid={!!error} />;
+```
+
+No alias is kept. `errorMessage` was retained nowhere on purpose — a tolerant
+second spelling is exactly the de-facto second contract AGENTS.md #0.1 forbids,
+and it is what would let a missed call site go quiet again. Because
+objectui#3221 had already removed the type's `[key: string]: any`, every missed
+site is a compile error rather than a silent `any`, so the compiler — not grep
+— validated this rename.
+
+## Responsibilities are split, not duplicated
+
+The widget consumes `error` **only** to drive `aria-invalid` on the control it
+renders (which only it can do — `aria-invalid` has to sit on the input element).
+The message TEXT stays with `<FormMessage/>` in the form renderer. A widget that
+also renders the text double-displays it, and the docs, the agent prompt and the
+tests all now say so.
+
+For the same reason `required` — also declared by the spec, also never delivered
+— is deliberately NOT lowered into widget props: the required marker has exactly
+one author, the renderer's `<FormLabel>`, and giving widgets the flag invites a
+second asterisk. The a11y state a widget could legitimately carry is
+`aria-required`, which needs no contract change at all (`AriaAttributes` is
+already part of the type and widgets already forward it).
+
+Builtin field types are unaffected: they render inside `<FormControl>`, whose
+Slot already supplies `aria-invalid`, so `error` is stripped there rather than
+leaking into the DOM as a stray attribute.
+
+Docs updated to match: `content/docs/guide/plugin-development.md`,
+`skills/objectui/guides/plugin-development.md` and
+`.github/prompts/component.prompt.md` — the last of which additionally used the
+spec's non-generic type alias as a generic (`FieldWidgetProps< number >`) and
+destructured a `mode` prop that exists on neither type.

.github/prompts/component.prompt.md

@@ -16,7 +16,7 @@
 
 2.  **Fields (@object-ui/fields):**
     *   Standard Input/Display widgets (Text, Number, Date, Select).
-    *   Must implement `FieldWidgetProps`.
+    *   Must implement `FieldWidgetComponentProps` (the package's own generic React interface — not the spec's non-generic `FieldWidgetProps` alias; see §2.A).
 
 3.  **Layouts & Patterns (@object-ui/layout):**
     *   Page structures (Sidebar, Header, AppLauncher).
@@ -35,15 +35,22 @@ You will be asked to build components in these 3 standard slots. Refer to `packa
 
 ### A. Field Widgets (`field:*`)
 Responsible for **Input** (Edit Mode) and **Display** (Read Mode) of a specific data type.
-*   **Contract:** Must implement `FieldWidgetProps` (Ref: `src/ui/widget.zod.ts`).
+*   **Contract:** Two layers with the same shape and DIFFERENT names — do not mix them up.
+    *   `FieldWidgetProps` (`@objectstack/spec/ui`, Ref: `src/ui/widget.zod.ts`) is the **declared** contract: a `z.infer` of `FieldWidgetPropsSchema`, so it is a plain **non-generic** type alias. Read it to learn what a widget receives.
+    *   `FieldWidgetComponentProps<T>` (`@object-ui/fields`) is the **implemented** React interface, and the one you actually import and parameterize when writing a widget in this repo.
     ```typescript
-    type FieldWidgetProps<T = any> = {
+    import type { FieldWidgetComponentProps } from '@object-ui/fields';
+
+    type FieldWidgetComponentProps<T = any> = {
       value: T;
       onChange: (val: T) => void;
-      field: FieldSchema; // Config
+      field: FieldMetadata; // Config
       readonly?: boolean;
+      disabled?: boolean;
+      error?: string;       // active validation message — see below
     }
     ```
+    The type is **closed**: a key it does not declare is a compile error, not a silent `any`.
 *   **Required Types (Ref: `src/data/field.zod.ts`):**
     *   **Textual:** `text` (Input), `textarea` (Multi-line), `password`, `email`, `url`, `phone`.
     *   **Rich Content:** `markdown` (Editor), `html` (WYSIWYG), `code` (Monaco/Ace).
@@ -168,24 +175,35 @@ Conversational and Generative UI components.
 ## 2. API Reference & Contracts
 
 ### A. Field Widget Implementation
-**Reference:** `@objectstack/spec` -> `dist/ui/widget.zod.d.ts`
+**Reference:** `packages/fields/src/widgets/types.ts` (implemented props), `@objectstack/spec` -> `dist/ui/widget.zod.d.ts` (declared contract)
+
+Import the **generic** `FieldWidgetComponentProps<T>` from `@object-ui/fields`.
+The spec's `FieldWidgetProps` is a non-generic alias — writing
+`FieldWidgetProps< number >` does not compile. There is no `mode` prop on
+either type; read-mode is `readonly`.
 
 ```typescript
-import { FieldWidgetProps } from '@objectstack/spec/ui';
-
-export function RatingField({ 
-  value, 
-  onChange, 
-  field, 
-  mode 
-}: FieldWidgetProps<number>) {
-  
-  if (mode === 'read') {
+import type { FieldWidgetComponentProps } from '@object-ui/fields';
+
+export function RatingField({
+  value,
+  onChange,
+  field,
+  readonly,
+  error,
+}: FieldWidgetComponentProps<number>) {
+
+  if (readonly) {
     return <span>{'★'.repeat(value || 0)}</span>;
   }
 
   return (
-    <div className="flex gap-1">
+    // `error` is the ACTIVE VALIDATION MESSAGE, supplied by the form renderer.
+    // Consume it as a boolean signal for a11y and nothing more: the message
+    // text is rendered by `<FormMessage/>` and the required marker by
+    // `<FormLabel>`, both in the form renderer. A widget that also prints the
+    // text double-displays it.
+    <div className="flex gap-1" role="radiogroup" aria-invalid={!!error}>
       {[1, 2, 3, 4, 5].map((star) => (
         <button 
           key={star}
@@ -240,7 +258,7 @@ export const widgetRegistry = {
 
 *   **Statelessness:** Widgets should rely on `props.value` and `props.onChange`. Avoid internal state unless necessary for transient UI interactions (like hover).
 *   **Schema Awareness:** The widget must respect schema options (e.g., `field.required`, `field.readonly`, `field.options`).
-*   **Validation:** Rendering logic should handle `props.errorMessage` gracefully.
+*   **Validation:** `props.error` is the active validation message. Use it for the a11y state (`aria-invalid={!!error}`) and nothing else — the host renders the message text and the required marker, so a widget that renders either shows it twice.
 *   **Accessibility:** Use standard ARIA roles and keyboard navigation (Shadcn UI/Radix primitives recommended).
 
 ---

content/docs/guide/plugin-development.md

@@ -187,10 +187,30 @@ type FieldWidgetComponentProps<T = any> = {
   readonly?: boolean;
   disabled?: boolean;
   className?: string;
-  errorMessage?: string;
+  error?: string;
 };
 ```
 
+The validation slot is named `error`, matching `FieldWidgetPropsSchema` in
+`@objectstack/spec/ui` — the published contract a widget is written against.
+The form renderer supplies it from the active validation message.
+
+### Who renders what
+
+The widget and the form renderer split validation display, and the split is
+not optional:
+
+| Concern | Owner |
+|---|---|
+| `aria-invalid` on the input | **the widget** — only it renders the input element |
+| the required marker (`*`) | **the form renderer** (`<FormLabel>`) |
+| the message TEXT | **the form renderer** (`<FormMessage/>`) |
+
+So consume `error` as a **boolean signal** — `aria-invalid={!!error}` — and do
+not render the message yourself. The form already prints it below the control;
+a widget that prints it too shows the user the same sentence twice. For the
+same reason `required` is not in the props: the marker has one author.
+
 ### Example: Color Picker Field
 
 ```tsx
@@ -205,7 +225,7 @@ export function ColorPickerField({
   field,
   readonly,
   disabled,
-  errorMessage,
+  error,
 }: FieldWidgetComponentProps<string>) {
   if (readonly) {
     return (
@@ -220,26 +240,24 @@ export function ColorPickerField({
   }
 
   return (
-    <div className="flex flex-col gap-1">
-      <div className="flex items-center gap-2">
-        <input
-          type="color"
-          value={value || '#000000'}
-          onChange={(e) => onChange(e.target.value)}
-          disabled={disabled}
-          className="h-8 w-8 cursor-pointer rounded border-0 p-0"
-        />
-        <Input
-          value={value || ''}
-          onChange={(e) => onChange(e.target.value)}
-          placeholder={field?.placeholder || '#000000'}
-          disabled={disabled}
-          className="font-mono text-sm"
-        />
-      </div>
-      {errorMessage && (
-        <span className="text-xs text-destructive">{errorMessage}</span>
-      )}
+    <div className="flex items-center gap-2">
+      <input
+        type="color"
+        value={value || '#000000'}
+        onChange={(e) => onChange(e.target.value)}
+        disabled={disabled}
+        className="h-8 w-8 cursor-pointer rounded border-0 p-0"
+      />
+      <Input
+        value={value || ''}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={field?.placeholder || '#000000'}
+        disabled={disabled}
+        className="font-mono text-sm"
+        // The whole job of `error` here: tell assistive tech the field failed.
+        // The message text is rendered by the form, not by this widget.
+        aria-invalid={!!error}
+      />
     </div>
   );
 }