@object-ui/fields 17.2.0 → 17.5.0

package/src/widgets/BooleanField.tsx

@@ -1,52 +1,86 @@
 import React, { useId } from 'react';
 import { Switch, Checkbox, Label } from '@object-ui/components';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 
 /**
  * BooleanField - Toggle input supporting switch and checkbox variants
  * Renders as Switch or Checkbox based on field widget configuration
  */
 export function BooleanField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<boolean>) {
-  const config = (field || (props as any).schema) as any;
+  const config = field as any;
   // Use simple type assertion for arbitrary custom properties not in BaseFieldMetadata
   const widget = config?.widget;
   // Generate unique ID using React's useId hook - must be before early returns (rules of hooks)
   const generatedId = useId();
-  const id = config?.name || generatedId;
+  /**
+   * The HOST owns the control's id (objectui#3952).
+   *
+   * `<FormControl>` is a Radix `Slot` that hands its child the id its
+   * `<FormLabel htmlFor>` already points at (`_r_N_-form-item`). This widget
+   * used to REPLACE it with the field name, so the form's visible label
+   * referenced an id no element carried: `label for="_r_3_-form-item"` against
+   * `all ids in form = ["notifications"]`. Clicking the label — the normal
+   * affordance for a switch/checkbox row — toggled nothing, on every generated
+   * form in every app.
+   *
+   * `id` is a DECLARED key of the widget contract (`FieldWidgetDomProps`) and
+   * `toDomProps` forwards it, so honouring it here is the contract's own
+   * direction: the fix belongs at the consumer that discarded a delivered
+   * value, not in the form renderer (AGENTS.md #0.1).
+   *
+   * The fallback chain stays for the STANDALONE hosts that hand down no id —
+   * `FieldEditWidget` (the grid's inline cell editor) and a bare SDUI node.
+   */
+  const hostId = props.id;
+  const id = hostId || config?.name || generatedId;
   const label = config?.label || 'Checkbox';
+  /**
+   * A host that supplies the id is a host that renders its own label for it
+   * (that is what the id is FOR), so the widget's `sr-only` label would be the
+   * second copy of one name — the other half of #3952, and why a naive
+   * `getByText(label)` on a boolean field returned two nodes.
+   *
+   * Standalone it is the control's ONLY accessible name (`FieldEditWidget`
+   * renders no label of its own), so there it stays. Deliberately keyed on the
+   * host id rather than on `config.label`: inside a form the naming is the
+   * host's job for EVERY widget — a text field in a label-less form row is
+   * equally unnamed — and the generic `'Checkbox'` fallback emitted there was
+   * an actively WRONG accessible name, not a safety net.
+   */
+  const emitOwnLabel = !hostId;
 
   if (readonly) {
     return <span className="text-sm">{value ? 'Yes' : 'No'}</span>;
   }
 
-  // Filter out non-DOM props
-  const { inputType, ...domProps } = props as any;
+  const domProps = toDomProps(props);
 
   if (widget === 'checkbox') {
      return (
         <div className="flex items-center space-x-2">
-            <Checkbox 
+            <Checkbox
                 {...domProps}
                 id={id}
                 checked={!!value}
                 onCheckedChange={(checked) => onChange(!!checked)}
                 disabled={readonly || domProps.disabled}
             />
-            <Label htmlFor={id} className="sr-only">{label}</Label>
+            {emitOwnLabel && <Label htmlFor={id} className="sr-only">{label}</Label>}
         </div>
      )
   }
 
   return (
     <div className="flex items-center space-x-2">
-        <Switch 
+        <Switch
             {...domProps}
-            id={id} 
-            checked={!!value} 
+            id={id}
+            checked={!!value}
             onCheckedChange={onChange}
             disabled={readonly || domProps.disabled}
         />
-        <Label htmlFor={id} className="sr-only">{label}</Label>
+        {emitOwnLabel && <Label htmlFor={id} className="sr-only">{label}</Label>}
     </div>
   );
 }

package/src/widgets/CapabilityMultiSelectField.tsx

@@ -18,9 +18,18 @@ import { useFieldTranslation } from './useFieldTranslation';
  * labelled, with the capability description on hover — while round-tripping the
  * stored value **byte-for-byte** as a JSON string of names.
  *
- * Reached via the field `widget: 'capability-multiselect'` hint (stamped onto
- * the object metadata in MetadataProvider), registered in the field registry as
- * `field:capability-multiselect`.
+ * ## Not a registry field widget (objectui#3308)
+ *
+ * This is a plain component, imported directly by its host — Studio's
+ * `PermissionMatrixEditor` (`packages/app-shell`), which is where ADR-0056 P2
+ * put the capability editor. It is deliberately NOT reachable through the field
+ * registry, and `widget: 'capability-multiselect'` is a **retired** hint: the
+ * key only ever existed on the docs-site-only `registerFields()` path, nothing
+ * ever stamped the hint (ADR-0056 P1 stamps `permission-facet-link` on all six
+ * `sys_permission_set` facets), and it was removed under ADR-0049
+ * enforce-or-remove. Do not re-register it without re-deciding ADR-0056 P2 —
+ * a field carrying that hint now degrades to its declared `type` renderer,
+ * which is the defined behavior for an unregistered widget.
  */
 
 interface Capability {
@@ -98,8 +107,11 @@ export function CapabilityMultiSelectField({
   const selected = React.useMemo(() => parseCapabilityNames(value), [value]);
 
   // Load the live capability registry (active only). Mirrors LookupField's
-  // context-dataSource access — createFieldRenderer does not forward the
-  // dataSource prop, so the SchemaRenderer context is the reliable source.
+  // context-dataSource access: no registration path forwards a `dataSource`
+  // prop to a field widget, so the SchemaRenderer context is the reliable
+  // source. (The absent forwarder named here used to be the docs-demo
+  // `createFieldRenderer`, removed in objectui#3910 — the conclusion is
+  // unchanged and now holds for the only remaining path.)
   React.useEffect(() => {
     if (!dataSource || typeof (dataSource as any).find !== 'function') return;
     let cancelled = false;

package/src/widgets/CharacterCount.tsx

@@ -0,0 +1,263 @@
+/**
+ * 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.
+ */
+
+import React, { useEffect, useState } from 'react';
+import { useFieldTranslation } from './useFieldTranslation';
+
+/**
+ * The character counter a capped long-text field renders, in the GOV.UK
+ * character-count shape — extracted from `TextAreaField` so that widget's TWO
+ * editing surfaces (the inline textarea and the fullscreen dialog) render the
+ * SAME counting UI instead of two hand-written copies (objectui#3417).
+ *
+ * ## Why this is shared rather than copied
+ *
+ * objectui#3408 gave the inline counter three nodes — decorative digits, an
+ * accessible description, a gated status region. The fullscreen dialog's
+ * counter, passed to `FullscreenFieldEditor` as a `footer`, stayed what it had
+ * always been: a bare `{n}/{max}` `span` with no accessible name, no
+ * `aria-describedby` association with the dialog's textarea, and nothing
+ * `aria-live`. Same field, same cap, same user — and a screen reader in the
+ * fullscreen dialog got nothing at all, while browse mode read "5 slash 500".
+ *
+ * That is the failure mode this package keeps paying for (objectui#3301: the
+ * fullscreen flag reached `RichTextField` for as long as the feature existed
+ * and that widget never read it). A second hand-written copy of a counting UI
+ * is the same failure with an extra step: it drifts, and nothing reports the
+ * drift. So the counter has ONE implementation and each surface renders it.
+ *
+ * ## The three nodes, and why the third is a prop
+ *
+ * 1. the visible `{n}/{max}` digits, `aria-hidden` — a glance affordance;
+ * 2. a visually-hidden DESCRIPTION carrying the translated sentence. The host
+ *    owns {@link CharacterCountProps.descriptionId} and MUST name it in the
+ *    edited control's `aria-describedby`, which is what makes the sentence
+ *    reachable on focus rather than only in browse mode;
+ * 3. a visually-hidden `aria-live="polite"` STATUS region, silent until the
+ *    value is inside the last 10% / 20 characters of the cap and updated only
+ *    after the typist pauses.
+ *
+ * Node 3 is opt-in per surface ({@link CharacterCountProps.announceNearLimit}),
+ * required rather than defaulted, because "should this surface interrupt the
+ * user while they type?" is a real decision and neither answer should be
+ * reached by leaving a prop off. The fullscreen dialog answers no: it is a
+ * modal the user opened deliberately to write at length, the description
+ * already tells them the cap on focus, and the dialog's own textarea carries
+ * the same native `maxLength` stop as the inline one. The inline surface
+ * answers yes, unchanged from objectui#3408.
+ */
+
+/**
+ * How long the typist must pause before the counter's status region is allowed
+ * to change (objectui#3408). The GOV.UK Design System character-count component
+ * uses the same shape and the same order of magnitude.
+ *
+ * The number this replaces was effectively 0: the counter WAS the live region,
+ * so every keystroke re-rendered it and every re-render was an announcement.
+ * Measured on `origin/main`, zh session, `maxLength: 500`, typing a 52-character
+ * sentence one character at a time: 52 keystrokes produced 52 distinct
+ * announcements totalling 979 spoken characters — ~19x the text the user was
+ * trying to write, each one interrupting the screen reader's echo of what they
+ * had just typed.
+ */
+const COUNTER_STATUS_DEBOUNCE_MS = 1000;
+
+/** Announce inside the last 10% of the cap … */
+const COUNTER_STATUS_REMAINING_RATIO = 0.1;
+/** … or the last 20 characters — whichever the typist reaches FIRST. */
+const COUNTER_STATUS_MIN_REMAINING = 20;
+
+/**
+ * The remaining-character count at or below which the status region speaks.
+ *
+ * "10% remaining OR 20 characters remaining, whichever comes first" is a
+ * disjunction, and because `remaining` only ever counts DOWN as the user types,
+ * the branch that fires first is simply the LARGER of the two — hence `max`.
+ * A 500-character cap starts warning at 50 remaining; a 100-character cap at 20
+ * (10% of it would be 10, which the typist would reach later, not sooner).
+ *
+ * A cap smaller than {@link COUNTER_STATUS_MIN_REMAINING} is therefore "near
+ * the limit" from the first keystroke, which is correct: on a 10-character
+ * field every character genuinely is one of the last few. The debounce still
+ * bounds it to one announcement per pause.
+ */
+function counterStatusThreshold(maxLength: number): number {
+  return Math.max(
+    Math.ceil(maxLength * COUNTER_STATUS_REMAINING_RATIO),
+    COUNTER_STATUS_MIN_REMAINING,
+  );
+}
+
+export interface CharacterCountProps {
+  /**
+   * Length of the text this surface is counting. The inline surface passes the
+   * committed value's length; the fullscreen dialog passes the DRAFT's, which
+   * is the number that is true of what the user is looking at.
+   */
+  length: number;
+  /**
+   * The declared cap. Callers render this component only when the field
+   * declares one, so it is non-optional here — a counter with no cap to count
+   * against has nothing to say and must not be mounted at all (an unconditional
+   * live region in every long-text field is the objectui#3408 defect back
+   * again).
+   */
+  maxLength: number;
+  /**
+   * The description node's `id`, minted by the host from `useId()`.
+   *
+   * The host MUST also name it in the edited control's `aria-describedby` —
+   * this component renders the sentence, only the host knows which element is
+   * being described, and a description nothing references is a node no screen
+   * reader will ever reach. That association is asserted from the OUTSIDE (the
+   * tests resolve `aria-describedby` and concatenate the referenced nodes' text,
+   * exactly as an assistive technology does) rather than trusted here.
+   *
+   * Two surfaces of one widget therefore need two ids: the dialog's draft and
+   * the inline value diverge the moment the user types in the dialog, so one
+   * shared id would point both controls at whichever sentence rendered last.
+   */
+  descriptionId: string;
+  /**
+   * Render node 3, the threshold-gated debounced `aria-live` status region.
+   *
+   * Required on purpose — see the component doc above. `false` removes the
+   * region from the DOM entirely (not merely empties it), which is the only
+   * form of "no live region" a test can tell apart from "a live region that
+   * happens to be silent right now".
+   */
+  announceNearLimit: boolean;
+  /**
+   * Classes for the visible digits. Required because placement is entirely the
+   * surface's business — inline pins them to the textarea's bottom-right
+   * corner, the dialog lays them out as a footer item — and a default borrowed
+   * from either one would position the other wrongly while looking deliberate.
+   */
+  className: string;
+  /**
+   * `data-testid` for the visible digits, namespaced per surface
+   * (`textarea-character-count`, `textarea-fullscreen-character-count`) so a
+   * test that finds digits can say WHICH surface it found them on. Same
+   * convention, same reason, as `FullscreenFieldEditor`'s `testIdPrefix`.
+   */
+  testId: string;
+}
+
+export function CharacterCount({
+  length,
+  maxLength,
+  descriptionId,
+  announceNearLimit,
+  className,
+  testId,
+}: CharacterCountProps) {
+  const { t } = useFieldTranslation();
+
+  /**
+   * The counter sentence as a DESCRIPTION (objectui#3408). Reached through the
+   * edited control's `aria-describedby`, so focusing it says "12 characters,
+   * 500 max" once and then shuts up. Before this the cap was announced only as
+   * a side effect of typing — focus told a screen reader user nothing at all
+   * that a sighted user could read off the corner of the box.
+   */
+  const description = t('fields.textarea.characterCount', { count: length, max: maxLength });
+
+  /**
+   * The near-limit warning, gated. Silent for the whole comfortable middle of
+   * the field — a count nobody is close to is not news — and phrased as what
+   * is LEFT rather than what has been typed, because that is the number the
+   * user is about to act on. Over-long values (a cap lowered after the record
+   * was saved) clamp to 0: the textarea's own `maxLength` blocks further
+   * input, so "0 left" is the true actionable state, and the description above
+   * still carries the honest `503 of 500`.
+   *
+   * Short-circuited by `announceNearLimit` rather than only hidden at render
+   * time, so a surface that renders no status region also schedules no timer —
+   * a debounce firing into a region that does not exist is a state update with
+   * no consumer, and in tests an `act()` warning with no cause.
+   */
+  const pendingStatus =
+    announceNearLimit && maxLength - length <= counterStatusThreshold(maxLength)
+      ? t('fields.textarea.charactersRemaining', { count: Math.max(maxLength - length, 0) })
+      : '';
+
+  /**
+   * The last sentence a PAUSE settled on. Only ever written by the timer —
+   * never cleared synchronously — so this effect adds no cascading render on
+   * the keystrokes it is busy staying quiet through
+   * (`react-hooks/set-state-in-effect`).
+   */
+  const [settledStatus, setSettledStatus] = useState('');
+
+  useEffect(() => {
+    if (!pendingStatus) return;
+    const timer = setTimeout(() => setSettledStatus(pendingStatus), COUNTER_STATUS_DEBOUNCE_MS);
+    // Every keystroke cancels the previous pending announcement, so a typist
+    // who never pauses is never interrupted. The dependency is the SENTENCE,
+    // not the length: re-typing back to the same count produces the same string
+    // and therefore no DOM change and no second announcement.
+    return () => clearTimeout(timer);
+  }, [pendingStatus]);
+
+  /**
+   * Speak the settled sentence only while it is still TRUE — i.e. while it is
+   * the one the current value would produce. Everything else renders empty,
+   * which costs no speech (emptying a live region announces nothing), and that
+   * is what makes leaving the warning band silent IMMEDIATELY rather than a
+   * second later.
+   *
+   * The obvious alternative, `pendingStatus ? settledStatus : ''`, is wrong in
+   * one specific way: delete back out of the band and type into it again, and
+   * the region re-announces the STALE count from before the excursion a full
+   * second before the timer corrects it. Announcing a wrong number is worse
+   * than announcing a right one twice, which is the bounded, sub-second,
+   * correct-content cost of the comparison below. Pinned by `never
+   * re-announces the STALE count when the user types back into the band`.
+   */
+  const status = settledStatus === pendingStatus ? pendingStatus : '';
+
+  return (
+    <>
+      {/*
+        The VISIBLE counter, and visible ONLY (objectui#3408). It used to be
+        three things at once: the digits a sighted user glances at, the carrier
+        of the translated sentence (objectui#3406), and the live region itself —
+        so the sentence was re-announced on every single keystroke. Split into
+        the three nodes here, this one is decorative: `aria-hidden` keeps a
+        screen reader from reading "5 slash 200" on top of the description that
+        says it properly.
+      */}
+      <div className={className} aria-hidden="true" data-testid={testId}>
+        {length}/{maxLength}
+      </div>
+
+      {/*
+        The DESCRIPTION. Referenced by the edited control's `aria-describedby`,
+        never announced on its own — a screen reader reads it when focus lands
+        on the control and not again. Visually hidden because the digits above
+        already say it to the eye.
+      */}
+      <span id={descriptionId} className="sr-only">
+        {description}
+      </span>
+
+      {/*
+        The STATUS region, on the surfaces that opted in. Rendered
+        unconditionally there and starting EMPTY on purpose: a live region has
+        to be in the DOM before its content changes or the first change is not
+        announced at all. `aria-atomic` so the whole sentence is spoken rather
+        than the digits that differ from last time.
+      */}
+      {announceNearLimit && (
+        <span className="sr-only" aria-live="polite" aria-atomic="true">
+          {status}
+        </span>
+      )}
+    </>
+  );
+}

package/src/widgets/CheckboxesField.tsx

@@ -2,6 +2,9 @@ import React, { useId, useEffect } from 'react';
 import { Checkbox, Label, EmptyValue, Badge } from '@object-ui/components';
 import type { OptionLike } from '@object-ui/core';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
+import { OptionsEmptyState } from './OptionsEmptyState';
 import { useCascadingOptions } from './useCascadingOptions';
 
 type Option = OptionLike;
@@ -24,14 +27,14 @@ export function CheckboxesField({
   field,
   readonly,
   className,
-  schema,
   dependentValues,
   dependsOn: dependsOnProp,
-  emptyHint: _emptyHint,
+  emptyHint,
   dataSource: _dataSource,
+  error,
   ...props
 }: FieldWidgetComponentProps<string[]>) {
-  const config = (field || schema) as any;
+  const config = field as any;
   const rawOptions: Option[] = config?.options || [];
   const selected: string[] = Array.isArray(value) ? value : value == null ? [] : [value as unknown as string];
   const groupId = useId();
@@ -49,16 +52,36 @@ export function CheckboxesField({
   // per-element clear the multi-value case needs (cf. the scalar select/radio).
   useEffect(() => {
     if (readonly) return;
+    // Never configured → nothing to prune against; see `MultiSelectField`'s
+    // copy of this guard for the measured failure (objectui#4220).
+    if (rawOptions.length === 0) return;
+    // Gated → the authored list is withheld until the `dependsOn` parent is
+    // chosen, so the empty offered set is missing information, not a verdict on
+    // the stored value; clearing here fired on mount (objectui#4247). Same
+    // reasoning, at length, in `MultiSelectField`.
+    if (gated) return;
     if (selected.length === 0) return;
     const stillOffered = selected.filter((v) => options.some((o) => o.value === v));
     if (stillOffered.length !== selected.length) onChange(stillOffered);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [options, gated]);
 
+  // The host's group label has to be consumed on EVERY surface this widget can
+  // render, not only the editable one (objectui#3990): both branches below
+  // return before the editable container's `groupDomProps` spread, which is how
+  // a field-level `readonly: true` and a zero-option list ended up with a
+  // published label id and no consumer at all. See `toHostGroupProps`.
+  const hostGroupProps = toHostGroupProps(props);
+
   if (readonly) {
-    if (selected.length === 0) return <EmptyValue />;
+    // The readonly display of a checkbox set is the set of CHECKED labels — a
+    // set of values, so the same `group` answer as the editable list.
+    // `EmptyValue` is that surface with nothing in it; its own `aria-label`
+    // ("No value") is outranked by `aria-labelledby` per accname, and on the
+    // `generic` role that span carries it was never exposed anyway.
+    if (selected.length === 0) return <EmptyValue {...hostGroupProps} />;
     return (
-      <div className="flex flex-wrap gap-1">
+      <div {...hostGroupProps} className="flex flex-wrap gap-1">
         {selected.map((v) => {
           // Label from the raw set so a stored value hidden by `visibleWhen`
           // still renders its label rather than a bare id.
@@ -70,19 +93,21 @@ export function CheckboxesField({
   }
 
   // No offered options is unfillable — surface a legible state instead of an
-  // empty checkbox list: a dependency-gated list prompts for its controlling
-  // field; an unconfigured / fully-filtered list says so. Mirrors the select.
+  // empty checkbox list: the host's `emptyHint` when it computed one, else this
+  // widget's own translated copy. Shared with the select / multiselect / radio
+  // so the four cannot drift again (objectui#3231).
   if (options.length === 0) {
-    const hint = gated
-      ? `Select ${dependsOnFields.join(' / ')} first`
-      : 'No options available';
     return (
-      <div
-        data-testid={fieldName ? `checkboxes-empty-${fieldName}` : undefined}
-        className="flex min-h-9 w-full items-center rounded-md border border-input bg-muted/30 px-3 py-2 text-sm text-muted-foreground"
-      >
-        {hint}
-      </div>
+      <OptionsEmptyState
+        emptyHint={emptyHint}
+        gated={gated}
+        dependsOnFields={dependsOnFields}
+        testId={fieldName ? `checkboxes-empty-${fieldName}` : undefined}
+        className="min-h-9"
+        // This box IS the field in this state, so it is what the host label
+        // names (objectui#3990).
+        hostGroupProps={hostGroupProps}
+      />
     );
   }
 
@@ -91,8 +116,32 @@ export function CheckboxesField({
     onChange(next);
   };
 
+  // DOM pass-through (objectui#3318): the container carries the form
+  // renderer's id / aria-describedby, but NOT its `aria-invalid` — a plain
+  // wrapper div is not where assistive tech reads the invalid state. That
+  // state goes onto every focusable checkbox below (`checkbox` is an
+  // aria-invalid-supporting role), computed from the published `error` slot
+  // (#3222). The per-item ids below stay authoritative for their labels.
+  // `name` is withheld too: it is only DOM-legal on form controls, and on
+  // this div it is exactly the leak #3291 sweeps for.
+  const {
+    'aria-invalid': _hostAriaInvalid,
+    name: _domName,
+    ...groupDomProps
+  } = toDomProps(props);
+  // When the host associated its visible label with this container by IDREF
+  // (`aria-labelledby`, objectui#3961) the container IS the labelled group, so it
+  // answers with the matching role — without one, the name sits on a generic
+  // `div` and contributes nothing: `label for` pointing here was already inert
+  // (`HTMLLabelElement.control` is null for a div), which is the whole defect.
+  // Absent (standalone: the inline grid editor, a bare SDUI node) nothing is
+  // emitted and the markup is unchanged.
+  const isLabelledGroup = groupDomProps['aria-labelledby'] != null;
+
   return (
     <div
+      {...groupDomProps}
+      role={isLabelledGroup ? 'group' : undefined}
       className={className}
       data-testid={fieldName ? `checkboxes-${fieldName}` : undefined}
     >
@@ -108,6 +157,7 @@ export function CheckboxesField({
               checked={selected.includes(value)}
               onCheckedChange={(checked) => toggle(value, !!checked)}
               disabled={props.disabled}
+              aria-invalid={!!error}
               data-testid={`checkboxes-option-${value}`}
             />
             <Label htmlFor={id} className="font-normal">{opt.label}</Label>

package/src/widgets/CodeField.tsx

@@ -1,14 +1,15 @@
 import React from 'react';
 import { Textarea, cn, EmptyValue } from '@object-ui/components';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 
 /**
  * Code field widget - provides a code editor with syntax highlighting
  * Uses a simple textarea with monospace font
  * For advanced code editing, use the @object-ui/plugin-editor component
  */
-export function CodeField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>) {
-  const config = field || (props as any).schema;
+export function CodeField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>) {
+  const config = field;
   // Get code-specific configuration from field metadata
   const language = (config as any)?.language ?? 'javascript';
 
@@ -22,6 +23,8 @@ export function CodeField({ value, onChange, field, readonly, ...props }: FieldW
 
   return (
     <Textarea
+      // DOM pass-through onto the real focusable control (objectui#3318).
+      {...toDomProps(props)}
       value={value || ''}
       onChange={(e) => onChange(e.target.value)}
       placeholder={config?.placeholder || `// Write ${language} code here...`}
@@ -29,6 +32,10 @@ export function CodeField({ value, onChange, field, readonly, ...props }: FieldW
       className={cn("font-mono text-sm", props.className)}
       rows={12}
       spellCheck={false}
+      // AFTER the spread so this widget's own computation wins: `error` is
+      // the published validation slot (#3222), `!!undefined` → explicit
+      // "false".
+      aria-invalid={!!error}
     />
   );
 }

package/src/widgets/ColorField.tsx

@@ -1,13 +1,14 @@
 import React from 'react';
 import { Input, EmptyValue } from '@object-ui/components';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 
 /**
  * Color field widget - provides a color picker input
  * Supports hex color values (e.g., #ff0000)
  */
-export function ColorField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>) {
-  const colorField = (field || (props as any).schema) as any;
+export function ColorField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>) {
+  const colorField = field as any;
 
   if (readonly) {
     return (
@@ -29,8 +30,14 @@ export function ColorField({ value, onChange, field, readonly, ...props }: Field
         onChange={(e) => onChange(e.target.value)}
         disabled={readonly || props.disabled}
         className="w-10 h-10 rounded border border-input cursor-pointer"
+        // Both focusable halves of this widget announce the same validation
+        // state (objectui#3318).
+        aria-invalid={!!error}
       />
       <Input
+        // DOM pass-through onto the primary text control (objectui#3318): the
+        // whitelist spread carries the form renderer's id / aria-describedby.
+        {...toDomProps(props)}
         type="text"
         value={value || ''}
         onChange={(e) => onChange(e.target.value)}
@@ -38,6 +45,8 @@ export function ColorField({ value, onChange, field, readonly, ...props }: Field
         disabled={readonly || props.disabled}
         className={props.className}
         pattern="^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$"
+        // AFTER the spread so this widget's own computation wins (#3222).
+        aria-invalid={!!error}
       />
     </div>
   );